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

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -1,6 +1,6 @@
 import { existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { relSliceFile, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
+import { join, relative } from "node:path";
+import { gsdProjectionRoot, gsdRoot, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -11,6 +11,14 @@ import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+function assessmentDbPathForRenderedFile(basePath, absPath) {
+    const projectionRoot = gsdProjectionRoot(basePath);
+    const projectionRel = relative(projectionRoot, absPath);
+    const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
+        ? projectionRoot
+        : gsdRoot(basePath);
+    return `.gsd/${relative(root, absPath).replace(/\\/g, "/")}`;
+}
 function validateParams(params) {
     if (!isNonEmptyString(params?.milestoneId))
         throw new Error("milestoneId is required");
@@ -74,10 +82,6 @@ export async function handleReassessRoadmap(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
-    // ── Compute assessment artifact path ──────────────────────────────
-    // Assessment lives in the completed slice's directory.
-    // Use relSliceFile so the path is layout-aware (flat-phase or legacy).
-    const assessmentRelPath = relSliceFile(basePath, params.milestoneId, params.completedSliceId, "ASSESSMENT");
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     // Guards must be inside the transaction so the state they check cannot
     // change between the read and the write (#2723).
@@ -152,15 +156,6 @@ export async function handleReassessRoadmap(rawParams, basePath) {
                     }
                 }
             }
-            // Record assessment
-            insertAssessment({
-                path: assessmentRelPath,
-                milestoneId: params.milestoneId,
-                sliceId: params.completedSliceId,
-                status: params.verdict,
-                scope: "roadmap",
-                fullContent: params.assessment,
-            });
             // Apply slice modifications
             for (const mod of params.sliceChanges.modified) {
                 updateSliceFields(params.milestoneId, mod.sliceId, {
@@ -220,6 +215,14 @@ export async function handleReassessRoadmap(rawParams, basePath) {
             assessment: params.assessment,
             completedSliceId: params.completedSliceId,
         });
+        insertAssessment({
+            path: assessmentDbPathForRenderedFile(basePath, assessmentResult.assessmentPath),
+            milestoneId: params.milestoneId,
+            sliceId: params.completedSliceId,
+            status: params.verdict,
+            scope: "roadmap",
+            fullContent: params.assessment,
+        });
         // ── Remove stale VALIDATION file from disk (#2957) ────────────
         const hasStructuralChanges = params.sliceChanges.added.length > 0 ||
             params.sliceChanges.modified.length > 0 ||

package/dist/resources/extensions/gsd/tools/reopen-milestone.js

@@ -16,7 +16,7 @@ import { logWarning } from "../workflow-logger.js";
 import { debugLog } from "../debug-logger.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { resolveMilestonePath, resolveSlicePath, resolveTasksDir, clearPathCache } from "../paths.js";
+import { buildFlatTaskFileName, buildTaskFileName, legacyMilestonesDir, resolveMilestonePath, resolveSlicePath, resolveTasksDir, clearPathCache, } from "../paths.js";
 export async function handleReopenMilestone(params, basePath) {
     // ── Validate required fields ────────────────────────────────────────────
     if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
@@ -41,6 +41,8 @@ export async function handleReopenMilestone(params, basePath) {
     // auto-corrects entities back to "complete", making reopen a no-op (#3161).
     try {
         const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+        const legacyBase = legacyMilestonesDir(basePath);
+        const isLegacy = !!milestoneDir && (milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\"));
         if (milestoneDir) {
             const milestoneSummary = join(milestoneDir, `${params.milestoneId}-SUMMARY.md`);
             if (existsSync(milestoneSummary))
@@ -58,10 +60,17 @@ export async function handleReopenMilestone(params, basePath) {
                     unlinkSync(sliceUat);
             }
             const tasksDir = resolveTasksDir(basePath, params.milestoneId, slice.id);
-            if (tasksDir) {
-                const tasks = getSliceTasks(params.milestoneId, slice.id);
-                for (const task of tasks) {
-                    const taskSummary = join(tasksDir, `${task.id}-SUMMARY.md`);
+            const tasks = getSliceTasks(params.milestoneId, slice.id);
+            for (const task of tasks) {
+                const taskSummaries = isLegacy
+                    ? (tasksDir ? [join(tasksDir, buildTaskFileName(task.id, "SUMMARY"))] : [])
+                    : milestoneDir
+                        ? [
+                            join(milestoneDir, buildFlatTaskFileName(slice.id, task.id, "SUMMARY")),
+                            join(milestoneDir, buildTaskFileName(task.id, "SUMMARY")),
+                        ]
+                        : [];
+                for (const taskSummary of taskSummaries) {
                     if (existsSync(taskSummary))
                         unlinkSync(taskSummary);
                 }

package/dist/resources/extensions/gsd/tools/reopen-slice.js

@@ -22,7 +22,7 @@ import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
+import { buildFlatTaskFileName, buildTaskFileName, legacyMilestonesDir, resolveMilestonePath, resolveTasksDir, resolveSlicePath, clearPathCache, } from "../paths.js";
 export async function handleReopenSlice(params, basePath) {
     // ── Validate required fields ────────────────────────────────────────────
     if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
@@ -52,11 +52,21 @@ export async function handleReopenSlice(params, basePath) {
     // Without this, the DB-filesystem reconciler sees SUMMARY.md files and
     // auto-corrects tasks back to "complete", making reopen a no-op (#3161).
     try {
+        const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+        const legacyBase = legacyMilestonesDir(basePath);
+        const isLegacy = !!milestoneDir && (milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\"));
         const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-        if (tasksDir) {
-            const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-            for (const task of tasks) {
-                const summaryPath = join(tasksDir, `${task.id}-SUMMARY.md`);
+        const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+        for (const task of tasks) {
+            const summaryPaths = isLegacy
+                ? (tasksDir ? [join(tasksDir, buildTaskFileName(task.id, "SUMMARY"))] : [])
+                : milestoneDir
+                    ? [
+                        join(milestoneDir, buildFlatTaskFileName(params.sliceId, task.id, "SUMMARY")),
+                        join(milestoneDir, buildTaskFileName(task.id, "SUMMARY")),
+                    ]
+                    : [];
+            for (const summaryPath of summaryPaths) {
                 if (existsSync(summaryPath))
                     unlinkSync(summaryPath);
             }

package/dist/resources/extensions/gsd/tools/reopen-task.js

@@ -17,8 +17,8 @@ import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { writeReopenReason } from "../reopen-reason.js";
 import { existsSync, unlinkSync } from "node:fs";
-import { join, basename, dirname } from "node:path";
-import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
+import { join } from "node:path";
+import { buildFlatTaskFileName, buildTaskFileName, legacyMilestonesDir, resolveMilestonePath, resolveTasksDir, resolveSlicePath, clearPathCache, } from "../paths.js";
 export async function handleReopenTask(params, basePath) {
     // ── Validate required fields ────────────────────────────────────────────
     if (!params.taskId || typeof params.taskId !== "string" || params.taskId.trim() === "") {
@@ -76,14 +76,20 @@ export async function handleReopenTask(params, basePath) {
     // summary cleanup into tasks/ (#1208).
     try {
         const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
-        if (slicePath) {
-            const isLegacySlice = basename(dirname(slicePath)) === "slices";
-            const summaryDir = isLegacySlice
-                ? (resolveTasksDir(basePath, params.milestoneId, params.sliceId) ?? slicePath)
-                : slicePath;
-            const summaryPath = join(summaryDir, `${params.taskId}-SUMMARY.md`);
-            if (existsSync(summaryPath))
-                unlinkSync(summaryPath);
+        const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+        if (milestonePath) {
+            const legacyBase = legacyMilestonesDir(basePath);
+            const isLegacy = milestonePath.startsWith(legacyBase + "/") || milestonePath.startsWith(legacyBase + "\\");
+            const summaryPaths = isLegacy
+                ? [join(resolveTasksDir(basePath, params.milestoneId, params.sliceId) ?? slicePath ?? join(milestonePath, "slices", params.sliceId, "tasks"), buildTaskFileName(params.taskId, "SUMMARY"))]
+                : [
+                    join(milestonePath, buildFlatTaskFileName(params.sliceId, params.taskId, "SUMMARY")),
+                    join(milestonePath, buildTaskFileName(params.taskId, "SUMMARY")),
+                ];
+            for (const summaryPath of summaryPaths) {
+                if (existsSync(summaryPath))
+                    unlinkSync(summaryPath);
+            }
         }
     }
     catch (cleanupErr) {

package/dist/resources/extensions/gsd/tools/replan-task.js

@@ -0,0 +1,128 @@
+import { clearParseCache } from "../files.js";
+import { getSlice, getTask, insertReplanHistory, transaction, upsertTaskPlanning, } from "../gsd-db.js";
+import { invalidateStateCache } from "../state.js";
+import { isClosedStatus } from "../status-guards.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
+import { renderPlanFromDb, renderTaskPlanFromDb } from "../markdown-renderer.js";
+import { resolveMilestonePath, resolveSlicePath } from "../paths.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
+import { logWarning } from "../workflow-logger.js";
+function validateParams(params) {
+    if (!isNonEmptyString(params?.milestoneId))
+        throw new Error("milestoneId is required");
+    if (!isNonEmptyString(params?.sliceId))
+        throw new Error("sliceId is required");
+    if (!isNonEmptyString(params?.taskId))
+        throw new Error("taskId is required");
+    if (!isNonEmptyString(params?.title))
+        throw new Error("title is required");
+    if (!isNonEmptyString(params?.description))
+        throw new Error("description is required");
+    if (!isNonEmptyString(params?.estimate))
+        throw new Error("estimate is required");
+    if (!isNonEmptyString(params?.verify))
+        throw new Error("verify is required");
+    return {
+        ...params,
+        files: validateStringArray(params.files, "files"),
+        inputs: validateStringArray(params.inputs, "inputs"),
+        expectedOutput: validateStringArray(params.expectedOutput, "expectedOutput"),
+    };
+}
+function replanSummary(params) {
+    const ref = params.reworkBriefRef?.trim();
+    return ref
+        ? `Task ${params.taskId} replanned from rework brief ${ref}`
+        : `Task ${params.taskId} replanned`;
+}
+export async function handleReplanTask(rawParams, basePath) {
+    let params;
+    try {
+        params = validateParams(rawParams);
+    }
+    catch (err) {
+        return { error: `validation failed: ${err.message}` };
+    }
+    let guardError = null;
+    try {
+        transaction(() => {
+            const parentSlice = getSlice(params.milestoneId, params.sliceId);
+            if (!parentSlice) {
+                guardError = `missing parent slice: ${params.milestoneId}/${params.sliceId}`;
+                return;
+            }
+            if (isClosedStatus(parentSlice.status)) {
+                guardError = `cannot replan a task in a closed slice: ${params.sliceId} (status: ${parentSlice.status})`;
+                return;
+            }
+            const task = getTask(params.milestoneId, params.sliceId, params.taskId);
+            if (!task) {
+                guardError = `task not found: ${params.milestoneId}/${params.sliceId}/${params.taskId}`;
+                return;
+            }
+            if (isClosedStatus(task.status)) {
+                guardError = `cannot replan completed task ${params.taskId} — use gsd_task_reopen first`;
+                return;
+            }
+            upsertTaskPlanning(params.milestoneId, params.sliceId, params.taskId, {
+                title: params.title,
+                description: params.description,
+                estimate: params.estimate,
+                files: params.files,
+                verify: params.verify,
+                inputs: params.inputs,
+                expectedOutput: params.expectedOutput,
+                fullPlanMd: params.fullPlanMd,
+            });
+            insertReplanHistory({
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                taskId: params.taskId,
+                summary: replanSummary(params),
+                previousArtifactPath: params.reworkBriefRef ?? null,
+            });
+        });
+    }
+    catch (err) {
+        return { error: `db write failed: ${err.message}` };
+    }
+    if (guardError)
+        return { error: guardError };
+    try {
+        const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+        const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+        const isLegacySliceLayout = Boolean(milestonePath && slicePath && slicePath !== milestonePath);
+        const renderResult = isLegacySliceLayout
+            ? await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId)
+            : await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+        const taskPlanPath = "taskPlanPath" in renderResult ? renderResult.taskPlanPath : renderResult.planPath;
+        invalidateStateCache();
+        clearParseCache();
+        try {
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
+            writeManifest(basePath);
+            appendEvent(basePath, {
+                cmd: "replan-task",
+                params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
+        catch (hookErr) {
+            logWarning("tool", `replan-task post-mutation hook warning: ${hookErr.message}`);
+        }
+        return {
+            milestoneId: params.milestoneId,
+            sliceId: params.sliceId,
+            taskId: params.taskId,
+            taskPlanPath,
+        };
+    }
+    catch (err) {
+        return { error: `render failed: ${err.message}` };
+    }
+}

package/dist/resources/extensions/gsd/tools/rework-brief.js

@@ -0,0 +1,74 @@
+import { saveReworkBrief } from "../gsd-db.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
+function validateFinding(finding, index) {
+    if (!isNonEmptyString(finding?.findingId))
+        throw new Error(`findings[${index}].findingId is required`);
+    if (finding.severity !== "blocking" && finding.severity !== "advisory") {
+        throw new Error(`findings[${index}].severity must be blocking or advisory`);
+    }
+    if (!isNonEmptyString(finding.description))
+        throw new Error(`findings[${index}].description is required`);
+    if (!isNonEmptyString(finding.requiredFix))
+        throw new Error(`findings[${index}].requiredFix is required`);
+    const status = finding.status ?? "pending";
+    if (status !== "pending" && status !== "resolved" && status !== "deferred-with-override") {
+        throw new Error(`findings[${index}].status must be pending, resolved, or deferred-with-override`);
+    }
+    // A blocking finding is only enforced by gsd_task_complete while it is
+    // `pending` (getUnresolvedBlockingReworkFindingsForTask returns pending rows
+    // only). Persisting a blocking finding as resolved/deferred-with-override
+    // at save time therefore bypasses the completion gate entirely, so require
+    // the same justification a reworkResolution would (evidence for `resolved`,
+    // evidence + decisionRef for `deferred-with-override`). Advisory findings do
+    // not gate completion, so their status is left as-is.
+    if (finding.severity === "blocking" && status !== "pending") {
+        if (!isNonEmptyString(finding.evidence)) {
+            throw new Error(`findings[${index}].evidence is required when a blocking finding is saved as ${status}`);
+        }
+        if (status === "deferred-with-override" && !isNonEmptyString(finding.decisionRef)) {
+            throw new Error(`findings[${index}].decisionRef is required when a blocking finding is saved as deferred-with-override`);
+        }
+    }
+    return {
+        ...finding,
+        verificationCommands: validateStringArray(finding.verificationCommands, `findings[${index}].verificationCommands`),
+        status,
+    };
+}
+function validateParams(params) {
+    if (!isNonEmptyString(params?.milestoneId))
+        throw new Error("milestoneId is required");
+    if (!isNonEmptyString(params?.sliceId))
+        throw new Error("sliceId is required");
+    if (!isNonEmptyString(params?.taskId))
+        throw new Error("taskId is required");
+    if (!Array.isArray(params.findings) || params.findings.length === 0) {
+        throw new Error("findings must be a non-empty array");
+    }
+    return {
+        ...params,
+        findings: params.findings.map(validateFinding),
+    };
+}
+export async function handleReworkBriefSave(rawParams) {
+    let params;
+    try {
+        params = validateParams(rawParams);
+    }
+    catch (err) {
+        return { error: `validation failed: ${err.message}` };
+    }
+    try {
+        const { briefId } = saveReworkBrief(params);
+        return {
+            briefId,
+            milestoneId: params.milestoneId,
+            sliceId: params.sliceId,
+            taskId: params.taskId,
+            findingCount: params.findings.length,
+        };
+    }
+    catch (err) {
+        return { error: `db write failed: ${err.message}` };
+    }
+}

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -18,6 +18,8 @@ import { handleCompleteSlice } from "./complete-slice.js";
 import { handlePlanMilestone } from "./plan-milestone.js";
 import { handlePlanSlice } from "./plan-slice.js";
 import { handleReplanSlice } from "./replan-slice.js";
+import { handleReplanTask } from "./replan-task.js";
+import { handleReworkBriefSave } from "./rework-brief.js";
 import { handleReopenMilestone } from "./reopen-milestone.js";
 import { handleReopenSlice } from "./reopen-slice.js";
 import { handleReopenTask } from "./reopen-task.js";
@@ -1277,6 +1279,85 @@ export async function executePlanSlice(params, basePath = process.cwd()) {
         };
     }
 }
+export async function executeReplanTask(params, basePath = process.cwd()) {
+    const dbAvailable = await ensureDbOpen(basePath);
+    if (!dbAvailable) {
+        return {
+            content: [{ type: "text", text: "Error: GSD database is not available. Cannot replan task." }],
+            details: { operation: "replan_task", error: "db_unavailable" },
+            isError: true,
+        };
+    }
+    try {
+        const result = await handleReplanTask(params, basePath);
+        if ("error" in result) {
+            return {
+                content: [{ type: "text", text: `Error replanning task: ${result.error}` }],
+                details: { operation: "replan_task", error: result.error },
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Replanned task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+            details: {
+                operation: "replan_task",
+                milestoneId: result.milestoneId,
+                sliceId: result.sliceId,
+                taskId: result.taskId,
+                taskPlanPath: result.taskPlanPath,
+            },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logError("tool", `replan_task tool failed: ${msg}`, { tool: "gsd_replan_task", error: String(err) });
+        return {
+            content: [{ type: "text", text: `Error replanning task: ${msg}` }],
+            details: { operation: "replan_task", error: msg },
+            isError: true,
+        };
+    }
+}
+export async function executeReworkBriefSave(params, basePath = process.cwd()) {
+    const dbAvailable = await ensureDbOpen(basePath);
+    if (!dbAvailable) {
+        return {
+            content: [{ type: "text", text: "Error: GSD database is not available. Cannot save rework brief." }],
+            details: { operation: "rework_brief_save", error: "db_unavailable" },
+            isError: true,
+        };
+    }
+    try {
+        const result = await handleReworkBriefSave(params);
+        if ("error" in result) {
+            return {
+                content: [{ type: "text", text: `Error saving rework brief: ${result.error}` }],
+                details: { operation: "rework_brief_save", error: result.error },
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Saved rework brief ${result.briefId} with ${result.findingCount} finding(s)` }],
+            details: {
+                operation: "rework_brief_save",
+                briefId: result.briefId,
+                milestoneId: result.milestoneId,
+                sliceId: result.sliceId,
+                taskId: result.taskId,
+                findingCount: result.findingCount,
+            },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logError("tool", `rework_brief_save tool failed: ${msg}`, { tool: "gsd_rework_brief_save", error: String(err) });
+        return {
+            content: [{ type: "text", text: `Error saving rework brief: ${msg}` }],
+            details: { operation: "rework_brief_save", error: msg },
+            isError: true,
+        };
+    }
+}
 export async function executeReplanSlice(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -36,6 +36,7 @@
 // owned by the unit, not in the composer. Reviews must enforce this — it
 // is the difference between an orchestrator and a runaway DSL.
 import { resolveManifest, } from "./unit-context-manifest.js";
+import { resolveEffectivePlanningToolsPolicy } from "./planning-subagent-policy.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 /**
  * Produce the inlined-context portion of a unit's system prompt by
@@ -148,11 +149,32 @@ const TOOL_SURFACE_GUIDANCE_BY_UNIT = {
     "validate-milestone": "Dispatch reviewer subagents in parallel, then persist the verdict via `gsd_validate_milestone`. Do not query `.gsd/gsd.db` directly — use `gsd_milestone_status` and inlined context.",
     "complete-milestone": "Persist completion only through `gsd_complete_milestone` after verification passes. Do not query `.gsd/gsd.db` directly. Do not write `.gsd/PROJECT.md` or `.gsd/REQUIREMENTS.md` by hand — use `gsd_summary_save` and `gsd_requirement_update`.",
     "replan-slice": "Persist replans through `gsd_replan_slice` only. Do not edit `PLAN.md` or task plans directly.",
-    "plan-slice": "Persist planning through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner** for reconnaissance — not implementation agents. Do not edit user source files outside `.gsd/**`.",
-    "refine-slice": "Persist refinements through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner**. Do not edit user source files outside `.gsd/**`.",
-    "plan-milestone": "Persist milestone planning through `gsd_plan_milestone` / `gsd_plan_slice`. Do not edit user source files outside `.gsd/**`.",
     "research-slice": "Dispatch subagents only to **scout** or **planner** for reconnaissance. Do not edit user source files outside `.gsd/**`.",
 };
+function formatAllowedAgents(agents) {
+    return agents.map((agent) => `**${agent}**`).join(", ");
+}
+function guidanceForUnitToolsPolicy(unitType, policy) {
+    if (unitType === "plan-slice") {
+        const dispatch = policy.mode === "planning-dispatch"
+            ? ` Dispatch subagents only to ${formatAllowedAgents(policy.allowedSubagents)} for reconnaissance — not implementation agents.`
+            : " Do not dispatch subagents.";
+        return `Persist planning through \`gsd_plan_slice\` only.${dispatch} Do not edit user source files outside \`.gsd/**\`.`;
+    }
+    if (unitType === "refine-slice") {
+        const dispatch = policy.mode === "planning-dispatch"
+            ? ` Dispatch subagents only to ${formatAllowedAgents(policy.allowedSubagents)}.`
+            : " Do not dispatch subagents.";
+        return `Persist refinements through \`gsd_plan_slice\` only.${dispatch} Do not edit user source files outside \`.gsd/**\`.`;
+    }
+    if (unitType === "plan-milestone") {
+        const dispatch = policy.mode === "planning-dispatch"
+            ? ` Dispatch subagents only to ${formatAllowedAgents(policy.allowedSubagents)}.`
+            : "";
+        return `Persist milestone planning through \`gsd_plan_milestone\` / \`gsd_plan_slice\`.${dispatch} Do not edit user source files outside \`.gsd/**\`.`;
+    }
+    return undefined;
+}
 function guidanceForToolsPolicy(policy) {
     switch (policy.mode) {
         case "planning":
@@ -191,8 +213,9 @@ export function composeToolSurfaceInstructions(unitType, opts) {
     const manifest = resolveManifest(unitType);
     if (!manifest)
         return "";
-    const unitGuidance = TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
-    const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(manifest.tools);
+    const effectiveTools = resolveEffectivePlanningToolsPolicy(unitType, manifest.tools, opts.basePath) ?? manifest.tools;
+    const unitGuidance = guidanceForUnitToolsPolicy(unitType, effectiveTools) ?? TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
+    const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(effectiveTools);
     const forbiddenLine = formatForbiddenWorkflowToolsLine(unitType, unitGuidance);
     const parts = [unitGuidance, policyGuidance, forbiddenLine].filter((part) => typeof part === "string" && part.length > 0);
     if (parts.length === 0)

package/dist/resources/extensions/gsd/unit-registry.js

@@ -232,6 +232,8 @@ export const UNIT_REGISTRY = {
                 "gsd_slice_complete",
                 "gsd_task_reopen",
                 "gsd_replan_slice",
+                "gsd_replan_task",
+                "gsd_rework_brief_save",
                 "gsd_decision_save",
                 "gsd_capture_thought",
                 "gsd_requirement_update",
@@ -245,6 +247,8 @@ export const UNIT_REGISTRY = {
                 "gsd_slice_complete",
                 "gsd_task_reopen",
                 "gsd_replan_slice",
+                "gsd_replan_task",
+                "gsd_rework_brief_save",
                 "gsd_requirement_update",
                 "gsd_summary_save",
             ],

package/dist/resources/extensions/gsd/uok/plan-v2.js

@@ -3,7 +3,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getTasksBySliceIds } from "../gsd-db.js";
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;
 export const EXECUTION_ENTRY_PHASES = new Set([
     "executing",
@@ -17,6 +17,19 @@ export function isExecutionEntryPhase(phase) {
 function graphOutputPath(basePath) {
     return join(gsdRoot(basePath), "runtime", "uok-plan-v2-graph.json");
 }
+// True when the on-disk graph matches `output` ignoring the volatile `compiledAt`
+// stamp, so redundant recompiles on the dispatch hot path skip the disk write.
+function graphBodyUnchanged(outPath, output) {
+    try {
+        const existing = JSON.parse(readFileSync(outPath, "utf-8"));
+        const { compiledAt: _existingStamp, ...existingBody } = existing;
+        const { compiledAt: _outputStamp, ...outputBody } = output;
+        return JSON.stringify(existingBody) === JSON.stringify(outputBody);
+    }
+    catch {
+        return false; // Missing, unreadable, or corrupt — write.
+    }
+}
 function hasFileContent(path) {
     if (!path || !existsSync(path))
         return false;
@@ -88,9 +101,10 @@ export function compileUnitGraphFromState(basePath, state) {
             finalizedContextIncluded,
         };
     }
+    const tasksBySlice = getTasksBySliceIds(slices.map((slice) => ({ milestoneId: mid, sliceId: slice.id })));
     for (const slice of slices) {
         const sid = slice.id;
-        const tasks = getSliceTasks(mid, sid)
+        const tasks = (tasksBySlice.get(`${mid}\0${sid}`) ?? [])
             .sort((a, b) => Number(a.sequence ?? 0) - Number(b.sequence ?? 0));
         let previousTaskNodeId = null;
         for (const task of tasks) {
@@ -138,7 +152,9 @@ export function compileUnitGraphFromState(basePath, state) {
     };
     const outPath = graphOutputPath(basePath);
     mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
-    writeFileSync(outPath, JSON.stringify(output, null, 2) + "\n", "utf-8");
+    if (!graphBodyUnchanged(outPath, output)) {
+        writeFileSync(outPath, JSON.stringify(output, null, 2) + "\n", "utf-8");
+    }
     return {
         ok: true,
         graphPath: outPath,

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -13,7 +13,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { deriveState } from "./state.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveTaskFile, relTaskFile } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveTaskFile, targetTaskFile } from "./paths.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────
 /**
  * Strip a leading ID prefix (e.g. "M001: " or "S04: ") from a title
@@ -276,8 +276,7 @@ export function renderSummaryProjection(basePath, milestoneId, sliceId, taskId)
         return;
     const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
     const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
-    const summaryPath = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY")
-        ?? join(basePath, relTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY", getMilestone(milestoneId)?.title));
+    const summaryPath = targetTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY", getMilestone(milestoneId)?.title);
     mkdirSync(dirname(summaryPath), { recursive: true });
     atomicWriteSync(summaryPath, content);
 }

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

@@ -2,6 +2,7 @@
 import { dirname, join, resolve } from "node:path";
 import { resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile, normalizeRealPath, } from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { milestoneMetaPath } from "./git-service.js";
 function tryRealpath(p) {
     return normalizeRealPath(p);
 }
@@ -63,7 +64,7 @@ export function scopeMilestone(workspace, milestoneId) {
         stateFile: () => join(gsd, "STATE.md"),
         dbPath: () => contract.projectDb,
         milestoneDir: () => scopeMilestoneDir(basePath, milestoneId),
-        metaJson: () => join(gsd, `${milestoneId}-META.json`),
+        metaJson: () => milestoneMetaPath(basePath, milestoneId),
     });
     return scope;
 }