@opengsd/gsd-pi 1.9.0 → 1.10.0

package/dist/resources/extensions/gsd/gsd-db.js

@@ -38,6 +38,7 @@ export * from "./db/queries.js";
 export * from "./db/writers/cascades.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) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -169,6 +170,44 @@ export function insertArtifact(a) {
         ":content_hash": contentHash,
     });
 }
+function canonicalPhaseDirNameForDb(milestoneId, title) {
+    const phaseNum = milestoneIdToPhaseNum(milestoneId);
+    const slug = derivePhaseSlug(title || milestoneId);
+    const suffix = milestoneIdUniqueSuffix(milestoneId);
+    return phaseDirName(phaseNum, suffix ? `${suffix}-${slug}` : slug);
+}
+function reconcileMilestonePhaseArtifactPaths(milestoneId, title) {
+    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}-%/%`,
+    });
+    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 function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -207,37 +246,42 @@ export function insertMilestone(m) {
 export function upsertMilestonePlanning(milestoneId, planning) {
     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);
     });
 }
 export function insertSlice(s) {

package/dist/resources/extensions/gsd/guided-flow.js

@@ -11,7 +11,7 @@ import { loadFile, saveFile } from "./files.js";
 import { isDbAvailable, getMilestone, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
-import { buildCompleteSlicePrompt, buildDiscussMilestonePrompt, buildExecuteTaskPrompt, buildPlanMilestonePrompt, buildPlanSlicePrompt, buildSkillActivationBlock, } from "./auto-prompts.js";
+import { buildCompleteSlicePrompt, buildDiscussMilestonePrompt, buildExecuteTaskPrompt, buildPlanMilestonePrompt, buildPlanSlicePrompt, buildSkillActivationBlock, capPreamble, } from "./auto-prompts.js";
 import { deriveState, isGhostMilestone } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
@@ -855,7 +855,9 @@ function resolveDiscussSliceBasePath(basePath, milestoneId) {
  * slice summaries so the agent can ask grounded UX/behaviour questions
  * without wasting a turn reading files.
  */
-async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
+// 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, sid, sTitle, base, options) {
     const inlined = [];
     // Roadmap — always included so the agent sees surrounding slices
     const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
@@ -906,8 +908,12 @@ async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
             }
         }
     }
+    // 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}`;
     const sliceContextPath = `${sliceDirPath}/${sid}-CONTEXT.md`;
@@ -916,7 +922,7 @@ async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
         ? `\n\n## Re-discuss Mode\n\nThis slice already has an existing context file (\`${sliceContextPath}\`) from a prior discussion. The user has chosen to re-discuss it. Read the existing context file, interview for any updates, changes, or new decisions, and rewrite the file with merged findings. Do NOT skip the interview — the user explicitly asked to revisit this slice.\n`
         : "";
     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,
@@ -927,7 +933,7 @@ async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
         inlinedTemplates,
         structuredQuestionsAvailable: options?.structuredQuestionsAvailable ?? "false",
         commitInstruction: buildDocsCommitInstruction(`docs(${mid}/${sid}): slice context from discuss`),
-    });
+    }));
 }
 /**
  * /gsd discuss — show a picker of non-done slices and run a slice interview.

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -11,14 +11,14 @@
 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, getMilestoneScopedArtifacts, getSliceScopedArtifacts, getMilestoneSlices, getSliceTasks, getTasksBySliceIds, getTask, getSlice, insertArtifact, deleteArtifactByPath, getGateResults, isDbAvailable, } from "./gsd-db.js";
-import { resolveDir, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, targetMilestoneFile, targetSliceFile, gsdProjectionRoot, gsdRoot, buildTaskFileName, } from "./paths.js";
+import { resolveDir, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, targetMilestoneFile, targetSliceFile, targetTaskFile, gsdProjectionRoot, gsdRoot, buildTaskFileName, } from "./paths.js";
 import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.js";
 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";
 // ─── Compat marker invalidation ───────────────────────────────────────────
 // Every successful projection write pushes its (basePath, projectionPath,
 // entities) here; invalidateCaches() drains it and refreshes .gsd/.compat.json
@@ -71,13 +71,7 @@ function flushProjectionWritesToMarker() {
  */
 function toArtifactPath(absPath, basePath) {
     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)]);
 }
 /**
  * Invalidate all caches after a disk write.
@@ -612,17 +606,7 @@ export async function renderTaskSummary(basePath, milestoneId, sliceId, taskId)
     if (!task || !task.full_summary_md) {
         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, {
         artifact_type: "SUMMARY",

package/dist/resources/extensions/gsd/md-importer.js

@@ -7,7 +7,7 @@ import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
 import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, transaction, updateMilestoneStatus, updateSliceStatus, getMilestoneSlices, getSliceTasks, _getAdapter, } from './gsd-db.js';
 import { openWorkflowDatabasePath } from './db-workspace.js';
-import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveMilestonePath, } from './paths.js';
+import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveTaskFile, resolveMilestonePath, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
 import { milestoneIdToPhaseNum } from './layout-policy.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
@@ -762,8 +762,7 @@ export function migrateHierarchyToDb(basePath, opts) {
                     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);
                 // Pre-migration consistency (legacy tasks/ layout only): if a task is
@@ -783,9 +782,9 @@ export function migrateHierarchyToDb(basePath, opts) {
                 // 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/dist/resources/extensions/gsd/model-cost-table.js

@@ -48,6 +48,8 @@ export const BUNDLED_COST_TABLE = [
     // 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" },
     { id: "gemini-flash-2.0", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },

package/dist/resources/extensions/gsd/model-router.js

@@ -46,10 +46,12 @@ export const MODEL_CAPABILITY_TIER = {
     "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) ───────────────────────
 // Used for cross-provider cost comparison when multiple providers offer
@@ -82,11 +84,13 @@ const MODEL_COST_PER_1K_INPUT = {
     "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 ──────────────────────────────────────────
 // Per-model capability profiles (0–100 scale). Used for capability-aware
@@ -128,6 +132,9 @@ export const MODEL_CAPABILITY_PROFILES = {
     // 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 },
     "o3": { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
@@ -139,6 +146,10 @@ export const MODEL_CAPABILITY_PROFILES = {
     "gemini-flash-2.0": { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 },
     // ── 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 ───────────────────────────────────────
 // Per-unit-type base requirement vectors. Weights indicate how important each

package/dist/resources/extensions/gsd/paths.js

@@ -122,6 +122,14 @@ function cachedReaddir(dirPath) {
     dirListCache.set(dirPath, entries);
     return entries;
 }
+function isExistingFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Clear the volatile directory listing caches.
  * Call after milestone transitions, file creation in planning directories,
@@ -198,6 +206,25 @@ export function buildTaskFileName(taskId, suffix) {
     // This helper is deprecated but kept for backward-compat callers.
     return `${taskId}-${suffix}.md`;
 }
+/**
+ * Build a flat-phase task artifact file name.
+ * ("S06", "T03", "SUMMARY") → "S06-T03-SUMMARY.md"
+ */
+export function buildFlatTaskFileName(sliceId, taskId, suffix) {
+    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, suffix) {
+    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 ─────────────────────────────────────────────────────────────
 /**
  * Find a directory entry by ID prefix within a parent directory.
@@ -238,7 +265,7 @@ export function resolveFile(dir, idPrefix, suffix) {
         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)
@@ -259,19 +286,18 @@ export function resolveFile(dir, idPrefix, suffix) {
     }
 }
 /**
- * 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, suffix) {
     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 {
@@ -810,7 +836,7 @@ export function resolveMilestoneFile(basePath, milestoneId, suffix) {
     const prefix = `${String(phaseNum).padStart(2, "0")}`;
     const flatName = `${prefix}-${suffix}.md`;
     const flatPath = join(mDir, flatName);
-    if (existsSync(flatPath))
+    if (isExistingFile(flatPath))
         return flatPath;
     // Legacy fallback: M001-SUFFIX.md
     const file = resolveFile(mDir, milestoneId, suffix);
@@ -843,12 +869,12 @@ export function resolveSliceFile(basePath, milestoneId, sliceId, suffix) {
     const planNum = sliceIdToPlanNum(sliceId);
     const flatName = planFileName(phaseNum, planNum, suffix);
     const flatPath = join(phaseDir, flatName);
-    if (existsSync(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))
+    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")}-`;
@@ -893,8 +919,11 @@ export function resolveTaskFile(basePath, milestoneId, sliceId, taskId, suffix)
     const legacyBase = legacyMilestonesDir(basePath);
     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);
     if (tDir) {
@@ -1006,6 +1035,28 @@ export function targetSliceFile(basePath, milestoneId, sliceId, suffix, mileston
         : planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), suffix);
     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, milestoneId, sliceId, taskId, suffix, milestoneTitle) {
+    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
@@ -1036,5 +1087,5 @@ export function relTaskFile(basePath, milestoneId, sliceId, taskId, suffix, mile
         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/dist/resources/extensions/gsd/planning-subagent-policy.js

@@ -0,0 +1,37 @@
+import { CONFIGURABLE_PLANNING_SUBAGENT_UNITS } from "./preferences-types.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+const CONFIGURABLE_UNITS = new Set(CONFIGURABLE_PLANNING_SUBAGENT_UNITS);
+function configuredAllowedSubagents(unitType, preferences) {
+    if (!CONFIGURABLE_UNITS.has(unitType))
+        return [];
+    return preferences?.planning_subagents?.[unitType]?.allowed ?? [];
+}
+function mergeAllowedSubagents(current, configured) {
+    return Array.from(new Set([...current, ...configured]));
+}
+export function applyPlanningSubagentPreferences(unitType, policy, preferences) {
+    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, policy, basePath) {
+    if (!basePath)
+        return policy;
+    const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
+    return applyPlanningSubagentPreferences(unitType, policy, preferences);
+}

package/dist/resources/extensions/gsd/planning-subagent-registry.js

@@ -0,0 +1,25 @@
+/**
+ * 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 },
+};
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set(Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId));
+export function isReadOnlyPlanningDispatchAgent(agentId) {
+    const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId];
+    return metadata?.readOnlySpecialist === true;
+}
+export function allowedPlanningDispatchAgentsList() {
+    return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}

package/dist/resources/extensions/gsd/preferences-types.js

@@ -61,6 +61,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "git",
     "post_unit_hooks",
     "pre_dispatch_hooks",
+    "planning_subagents",
     "dynamic_routing",
     "disabled_model_providers",
     "uok",
@@ -134,6 +135,10 @@ export const KNOWN_UNIT_LABELS = [
     "workflow-preferences", "discuss-project", "discuss-requirements",
     "research-decision", "research-project",
 ];
+export const CONFIGURABLE_PLANNING_SUBAGENT_UNITS = [
+    "plan-milestone",
+    "plan-slice",
+];
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 /** The nine model-routing phase buckets. */
 export const GSD_MODEL_PHASE_KEYS = [

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -9,7 +9,8 @@ import { isAbsolute } from "node:path";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { getGateIdsForTurn } from "./gate-registry.js";
-import { KNOWN_PREFERENCE_KEYS, KNOWN_UNIT_LABELS, GSD_MODEL_PHASE_KEYS, SKILL_ACTIONS, } from "./preferences-types.js";
+import { KNOWN_PREFERENCE_KEYS, KNOWN_UNIT_LABELS, CONFIGURABLE_PLANNING_SUBAGENT_UNITS, GSD_MODEL_PHASE_KEYS, SKILL_ACTIONS, } from "./preferences-types.js";
+import { ALLOWED_PLANNING_DISPATCH_AGENTS, allowedPlanningDispatchAgentsList, } from "./planning-subagent-registry.js";
 const VALID_TOKEN_PROFILES = new Set(["budget", "balanced", "quality", "burn-max"]);
 const VALID_THINKING_LEVELS = new Set([
     "off",
@@ -727,6 +728,52 @@ export function validatePreferences(preferences) {
             validated.pre_dispatch_hooks = validPreHooks;
         }
     }
+    // ─── Planning Subagents ─────────────────────────────────────────────────
+    if (preferences.planning_subagents !== undefined) {
+        if (!preferences.planning_subagents ||
+            typeof preferences.planning_subagents !== "object" ||
+            Array.isArray(preferences.planning_subagents)) {
+            errors.push("planning_subagents must be an object keyed by planning unit type");
+        }
+        else {
+            const validUnits = new Set(CONFIGURABLE_PLANNING_SUBAGENT_UNITS);
+            const validPlanningSubagents = {};
+            for (const [unitType, rawConfig] of Object.entries(preferences.planning_subagents)) {
+                if (!validUnits.has(unitType)) {
+                    errors.push(`planning_subagents unknown or unsupported unit "${unitType}" — supported units: ` +
+                        `${CONFIGURABLE_PLANNING_SUBAGENT_UNITS.join(", ")}`);
+                    continue;
+                }
+                if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
+                    errors.push(`planning_subagents.${unitType} must be an object with an allowed array`);
+                    continue;
+                }
+                const allowed = normalizeStringArray(rawConfig.allowed);
+                if (allowed.length === 0) {
+                    errors.push(`planning_subagents.${unitType}.allowed must include at least one read-only planning specialist`);
+                    continue;
+                }
+                const sanitizedAllowed = [];
+                for (const agentId of allowed) {
+                    if (!ALLOWED_PLANNING_DISPATCH_AGENTS.has(agentId)) {
+                        errors.push(`planning_subagents.${unitType}.allowed includes "${agentId}", which is not classified as a ` +
+                            `read-only planning specialist. Allowed agents: ${allowedPlanningDispatchAgentsList()}`);
+                        continue;
+                    }
+                    sanitizedAllowed.push(agentId);
+                }
+                const dedupedAllowed = Array.from(new Set(sanitizedAllowed));
+                if (dedupedAllowed.length > 0) {
+                    validPlanningSubagents[unitType] = {
+                        allowed: dedupedAllowed,
+                    };
+                }
+            }
+            if (Object.keys(validPlanningSubagents).length > 0) {
+                validated.planning_subagents = validPlanningSubagents;
+            }
+        }
+    }
     // ─── Dynamic Routing ─────────────────────────────────────────────────
     if (preferences.dynamic_routing !== undefined) {
         if (typeof preferences.dynamic_routing === "object" && preferences.dynamic_routing !== null) {