@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -7,7 +7,6 @@ import { getGateIdsForTurn } from "../gate-registry.js";
 import { transaction, getMilestone, getSlice, getSliceTasks, insertTask, upsertSlicePlanning, upsertTaskPlanning, insertGateRow, updateSliceStatus, setSliceSketchFlag, deleteTask, deleteArtifactByPath, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.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";
@@ -29,9 +28,13 @@ function validateRepositoryTargetIds(field, value) {
     return deduped;
 }
 function validateTasks(value) {
-    if (!Array.isArray(value) || value.length === 0) {
-        throw new Error("tasks must be a non-empty array");
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("tasks must be an array");
     }
+    if (value.length === 0)
+        return undefined;
     const seen = new Set();
     return value.map((entry, index) => {
         if (!entry || typeof entry !== "object") {
@@ -130,7 +133,7 @@ function validateReferencedRepositories(params, registry, defaultTargets) {
     };
     for (const id of params.targetRepositories ?? defaultTargets)
         noteMissing(id);
-    for (const task of params.tasks) {
+    for (const task of params.tasks ?? []) {
         for (const id of task.targetRepositories ?? params.targetRepositories ?? defaultTargets)
             noteMissing(id);
     }
@@ -142,7 +145,7 @@ function resolveAllowedRootsForPathScope(params, registry, defaultTargets) {
     const requested = new Set();
     for (const id of params.targetRepositories ?? defaultTargets)
         requested.add(id);
-    for (const task of params.tasks) {
+    for (const task of params.tasks ?? []) {
         for (const id of task.targetRepositories ?? params.targetRepositories ?? defaultTargets)
             requested.add(id);
     }
@@ -154,7 +157,7 @@ function resolveAllowedRootsForPathScope(params, registry, defaultTargets) {
     return roots.length > 0 ? roots : [registry.projectRoot];
 }
 function toTaskRows(params, defaultTargets) {
-    return params.tasks.map((task, index) => ({
+    return (params.tasks ?? []).map((task, index) => ({
         milestone_id: params.milestoneId,
         slice_id: params.sliceId,
         id: task.taskId,
@@ -231,19 +234,21 @@ export async function handlePlanSlice(rawParams, basePath) {
         return { error: `validation failed: ${message}` };
     }
     const defaultTargets = defaultRepositoryTargets(repositoryRegistry);
+    const taskPayload = params.tasks ?? [];
+    const hasTaskPayload = taskPayload.length > 0;
     const repoValidationError = validateReferencedRepositories(params, repositoryRegistry, defaultTargets);
     if (repoValidationError) {
         return { error: `validation failed: ${repoValidationError}` };
     }
     const allowedAbsoluteRoots = resolveAllowedRootsForPathScope(params, repositoryRegistry, defaultTargets);
-    const pathOnlyError = validatePathOnlyPlanningFields(params.tasks.map((task, index) => ({
+    const pathOnlyError = validatePathOnlyPlanningFields(taskPayload.map((task, index) => ({
         field: `tasks[${index}].expectedOutput`,
         values: task.expectedOutput,
     })));
     if (pathOnlyError) {
         return { error: `validation failed: ${pathOnlyError}` };
     }
-    const pathScopeError = validatePlanningPathScope(basePath, params.tasks.flatMap((task, index) => [
+    const pathScopeError = validatePlanningPathScope(basePath, taskPayload.flatMap((task, index) => [
         { field: `tasks[${index}].files`, values: task.files },
         { field: `tasks[${index}].inputs`, values: task.inputs },
         { field: `tasks[${index}].expectedOutput`, values: task.expectedOutput },
@@ -280,15 +285,17 @@ export async function handlePlanSlice(rawParams, basePath) {
                 guardError = `cannot re-plan slice ${params.sliceId}: it is already complete — use gsd_slice_reopen first`;
                 return;
             }
-            const newTaskIds = new Set(params.tasks.map((task) => task.taskId));
+            const newTaskIds = new Set(taskPayload.map((task) => task.taskId));
             const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
-            omittedTaskIds = existingTasks
-                .filter((task) => !newTaskIds.has(task.id))
-                .map((task) => task.id);
-            for (const task of existingTasks) {
-                if (!newTaskIds.has(task.id) && isClosedStatus(task.status)) {
-                    guardError = `cannot remove completed task ${task.id}`;
-                    return;
+            if (hasTaskPayload) {
+                omittedTaskIds = existingTasks
+                    .filter((task) => !newTaskIds.has(task.id))
+                    .map((task) => task.id);
+                for (const task of existingTasks) {
+                    if (!newTaskIds.has(task.id) && isClosedStatus(task.status)) {
+                        guardError = `cannot remove completed task ${task.id}`;
+                        return;
+                    }
                 }
             }
             if (isDeferredStatus(parentSlice.status)) {
@@ -302,34 +309,36 @@ export async function handlePlanSlice(rawParams, basePath) {
                 observabilityImpact: params.observabilityImpact,
                 targetRepositories: params.targetRepositories ?? defaultTargets,
             });
-            for (const taskId of omittedTaskIds) {
-                deleteTask(params.milestoneId, params.sliceId, taskId);
-            }
-            const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
-            for (const task of params.tasks) {
-                const planning = {
-                    title: task.title,
-                    description: task.description,
-                    estimate: task.estimate,
-                    files: task.files,
-                    verify: task.verify,
-                    inputs: task.inputs,
-                    expectedOutput: task.expectedOutput,
-                    observabilityImpact: task.observabilityImpact ?? "",
-                    fullPlanMd: task.fullPlanMd,
-                    targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
-                };
-                const existingTask = existingTaskById.get(task.taskId);
-                if (!existingTask || !isClosedStatus(existingTask.status)) {
-                    insertTask({
-                        id: task.taskId,
-                        sliceId: params.sliceId,
-                        milestoneId: params.milestoneId,
+            if (hasTaskPayload) {
+                for (const taskId of omittedTaskIds) {
+                    deleteTask(params.milestoneId, params.sliceId, taskId);
+                }
+                const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
+                for (const task of taskPayload) {
+                    const planning = {
                         title: task.title,
-                        status: "pending",
-                    });
+                        description: task.description,
+                        estimate: task.estimate,
+                        files: task.files,
+                        verify: task.verify,
+                        inputs: task.inputs,
+                        expectedOutput: task.expectedOutput,
+                        observabilityImpact: task.observabilityImpact ?? "",
+                        fullPlanMd: task.fullPlanMd,
+                        targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
+                    };
+                    const existingTask = existingTaskById.get(task.taskId);
+                    if (!existingTask || !isClosedStatus(existingTask.status)) {
+                        insertTask({
+                            id: task.taskId,
+                            sliceId: params.sliceId,
+                            milestoneId: params.milestoneId,
+                            title: task.title,
+                            status: "pending",
+                        });
+                    }
+                    upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
                 }
-                upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
             }
             // Seed quality gate rows inside the transaction — all-or-nothing with
             // the plan data so a crash can't leave orphaned gates without tasks.
@@ -338,7 +347,7 @@ export async function handlePlanSlice(rawParams, basePath) {
                 insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "slice" });
             }
             const taskGates = resolveTaskGates(gateEvaluation);
-            for (const task of params.tasks) {
+            for (const task of taskPayload) {
                 for (const gid of taskGates) {
                     insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: task.taskId });
                 }
@@ -361,13 +370,17 @@ export async function handlePlanSlice(rawParams, basePath) {
             const artifactPath = relative(gsdProjectionRoot(basePath), taskPlanPath).replace(/\\/g, "/");
             deleteArtifactByPath(artifactPath);
         }
-        const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
-        setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+        const sliceTasks = getSliceTasks(params.milestoneId, params.sliceId);
+        const renderResult = sliceTasks.length === 0
+            ? { planPath: "", taskPlanPaths: [] }
+            : await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+        if (sliceTasks.length > 0) {
+            setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+        }
         invalidateStateCache();
         clearParseCache();
-        // ── Post-mutation hook: projections, manifest, event log ─────────────
+        // ── Post-mutation hook: manifest, event log ─────────────────────────
         try {
-            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "plan-slice",

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

@@ -1,13 +1,16 @@
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
-import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
+import { getGateIdsForTurn } from "../gate-registry.js";
+import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning, insertGateRow, setSliceSketchFlag } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderTaskPlanFromDb } from "../markdown-renderer.js";
+import { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
+import { resolveTasksDir } 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";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
 function validateParams(params) {
     if (!isNonEmptyString(params?.milestoneId))
@@ -34,6 +37,12 @@ function validateParams(params) {
         expectedOutput: validateStringArray(params.expectedOutput, "expectedOutput"),
     };
 }
+function resolveTaskGates(basePath) {
+    const loaded = loadEffectiveGSDPreferences(basePath);
+    if (loaded?.preferences?.gate_evaluation?.task_gates === false)
+        return [];
+    return [...getGateIdsForTurn("execute-task")];
+}
 export async function handlePlanTask(rawParams, basePath) {
     let params;
     try {
@@ -56,6 +65,14 @@ export async function handlePlanTask(rawParams, basePath) {
     if (pathScopeError) {
         return { error: `validation failed: ${pathScopeError}` };
     }
+    let taskGates;
+    try {
+        taskGates = resolveTaskGates(basePath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: `validation failed: ${message}` };
+    }
     // ── 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).
@@ -96,6 +113,9 @@ export async function handlePlanTask(rawParams, basePath) {
                 observabilityImpact: params.observabilityImpact ?? "",
                 fullPlanMd: params.fullPlanMd,
             });
+            for (const gid of taskGates) {
+                insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: params.taskId });
+            }
         });
     }
     catch (err) {
@@ -106,6 +126,24 @@ export async function handlePlanTask(rawParams, basePath) {
     }
     try {
         const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
+        // Flat-phase: tasks live as checkboxes in the slice plan's <tasks> block,
+        // not as standalone TID-PLAN.md files. Re-render the slice plan so the
+        // new/updated task appears in the plan file that gsd-core reads.
+        // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists).
+        let slicePlanSynced = false;
+        try {
+            const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+            if (!tDir) {
+                await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+                slicePlanSynced = true;
+            }
+        }
+        catch (syncErr) {
+            logWarning("tool", `plan-task: slice-plan sync failed: ${syncErr.message}`);
+        }
+        if (slicePlanSynced) {
+            setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+        }
         invalidateStateCache();
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────────────

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

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { existsSync, unlinkSync } from "node:fs";
+import { relSliceFile, relMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -74,8 +75,9 @@ export async function handleReassessRoadmap(rawParams, basePath) {
         return { error: `validation failed: ${err.message}` };
     }
     // ── Compute assessment artifact path ──────────────────────────────
-    // Assessment lives in the completed slice's directory
-    const assessmentRelPath = join(".gsd", "milestones", params.milestoneId, "slices", params.completedSliceId, `${params.completedSliceId}-ASSESSMENT.md`);
+    // 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).
@@ -210,6 +212,9 @@ export async function handleReassessRoadmap(rawParams, basePath) {
     // ── Render artifacts ──────────────────────────────────────────────
     try {
         const roadmapResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+        if ("skipped" in roadmapResult) {
+            return { error: `roadmap render skipped: milestone ${params.milestoneId} has no planned slices` };
+        }
         const assessmentResult = await renderAssessmentFromDb(basePath, params.milestoneId, params.completedSliceId, {
             verdict: params.verdict,
             assessment: params.assessment,
@@ -220,7 +225,8 @@ export async function handleReassessRoadmap(rawParams, basePath) {
             params.sliceChanges.modified.length > 0 ||
             params.sliceChanges.removed.length > 0;
         if (hasStructuralChanges) {
-            const validationFile = join(basePath, ".gsd", "milestones", params.milestoneId, `${params.milestoneId}-VALIDATION.md`);
+            // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md; legacy → milestones/MID/MID-VALIDATION.md
+            const validationFile = join(basePath, relMilestoneFile(basePath, params.milestoneId, "VALIDATION"));
             try {
                 if (existsSync(validationFile))
                     unlinkSync(validationFile);

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

@@ -12,7 +12,7 @@
  */
 import { join } from "node:path";
 import { transaction, insertAssessment, getMilestoneSlices, getMilestone, } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -113,7 +113,11 @@ export async function handleValidateMilestone(params, basePath, opts) {
     // worktree exists for this milestone, validation reads/writes the
     // worktree's artifacts instead of stale project-root state.
     const validationMd = renderValidationMarkdown(effectiveParams);
-    const validationPath = join(gsdProjectionRoot(artifactBasePath), "milestones", effectiveParams.milestoneId, `${effectiveParams.milestoneId}-VALIDATION.md`);
+    // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md;
+    // legacy → milestones/MID/MID-VALIDATION.md.
+    // join(artifactBasePath, relMilestoneFile) gives the absolute path; relMilestoneFile
+    // returns ".gsd/..."-relative so joining with basePath (project/worktree root) is correct.
+    const validationPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, effectiveParams.milestoneId, "VALIDATION"));
     // ── DB write first — matches complete-task/complete-slice pattern ───
     // Write DB before disk so a crash between the two leaves a recoverable
     // state: the DB row exists but the file is missing, which projection
@@ -143,7 +147,8 @@ export async function handleValidateMilestone(params, basePath, opts) {
         await saveFile(validationPath, validationMd);
         const projectRoot = resolveWorktreeProjectRoot(basePath);
         if (projectRoot !== artifactBasePath) {
-            const projectValidationPath = join(gsdProjectionRoot(projectRoot), "milestones", effectiveParams.milestoneId, `${effectiveParams.milestoneId}-VALIDATION.md`);
+            // Mirror to project root using the project root's layout (same logic as above).
+            const projectValidationPath = join(projectRoot, relMilestoneFile(projectRoot, effectiveParams.milestoneId, "VALIDATION"));
             try {
                 await saveFile(projectValidationPath, validationMd);
             }

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

@@ -3,10 +3,11 @@
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js";
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
-import { getActiveRequirements, getAllMilestones, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertMilestone, insertAssessment, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } from "../gsd-db.js";
+import { getActiveRequirements, getAllMilestones, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertMilestone, insertAssessment, insertGateRun, readTransaction, saveGateResult, upsertMilestonePlanning, upsertQualityGate, } from "../gsd-db.js";
+import { extractMilestoneSeq } from "../milestone-ids.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relMilestoneFile, relSliceFile, relSlicePath, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
 import { hostname } from "node:os";
@@ -80,7 +81,35 @@ function milestoneLeaseConflictResult(milestoneId, byWorker, expiresAt) {
 function registerProjectMilestoneSequence(content) {
     const parsed = parseProject(content);
     const registered = [];
+    // Reconcile parsed IDs against existing DB milestones before inserting (#807).
+    // Under unique_milestone_ids the planner mints suffixed IDs (e.g. "M001-b1nole"),
+    // while PROJECT.md's template uses bare sequence IDs (e.g. "M001"). Inserting the
+    // bare ID verbatim mints a phantom milestone row that collides with the planner's
+    // canonical one: the bare row gets its own git worktree, and at dispatch time the
+    // worktree/session scope ("M001") disagrees with ctx.mid ("M001-b1nole"), pausing
+    // auto-mode with "Dispatch milestone mismatch". A project DB holds at most one
+    // milestone per sequence number, so map each parsed line onto the existing row
+    // that shares its sequence number instead of minting a duplicate bare-ID row.
+    const existingBySeq = new Map();
+    for (const existing of getAllMilestones()) {
+        const seq = extractMilestoneSeq(existing.id);
+        if (seq > 0 && !existingBySeq.has(seq))
+            existingBySeq.set(seq, existing.id);
+    }
     for (const milestone of parsed.milestones) {
+        const canonicalId = existingBySeq.get(extractMilestoneSeq(milestone.id));
+        if (canonicalId && canonicalId !== milestone.id) {
+            // An existing milestone already owns this sequence number. Treat the markdown
+            // line as referring to it: refresh the human title, and promote to complete
+            // when the line is checked — but never demote an in-flight milestone back to
+            // "queued" (the planner's row stays the single source of truth).
+            upsertMilestonePlanning(canonicalId, {
+                title: milestone.title,
+                ...(milestone.done ? { status: "complete" } : {}),
+            });
+            registered.push(canonicalId);
+            continue;
+        }
         insertMilestone({
             id: milestone.id,
             title: milestone.title,
@@ -270,13 +299,23 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
             relativePath = "REQUIREMENTS-DRAFT.md";
         }
         else if (params.task_id && params.slice_id) {
-            relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
+            // Layout-aware path for task-scoped artifacts.
+            // Flat-phase: <phaseDir>/TID-TYPE.md  Legacy: milestones/MID/slices/SID/tasks/TID-TYPE.md
+            // relSlicePath returns ".gsd/phases/NN-slug" (flat) or ".gsd/milestones/MID/slices/SID" (legacy).
+            const sRel = relSlicePath(basePath, params.milestone_id, params.slice_id).replace(/^\.gsd\//, "");
+            relativePath = sRel.startsWith("milestones/")
+                ? `${sRel}/tasks/${params.task_id}-${params.artifact_type}.md`
+                : `${sRel}/${params.task_id}-${params.artifact_type}.md`;
         }
         else if (params.slice_id) {
-            relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
+            // Layout-aware path for slice-scoped artifacts.
+            // relSliceFile returns ".gsd/..." prefix — strip it to get the DB-relative path.
+            relativePath = relSliceFile(basePath, params.milestone_id, params.slice_id, params.artifact_type).replace(/^\.gsd\//, "");
         }
         else {
-            relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
+            // Layout-aware path for milestone-scoped artifacts.
+            // relMilestoneFile returns ".gsd/..." prefix — strip it to get the DB-relative path.
+            relativePath = relMilestoneFile(basePath, params.milestone_id, params.artifact_type).replace(/^\.gsd\//, "");
         }
         const activeRequirements = params.artifact_type === "REQUIREMENTS"
             ? getActiveRequirements()

package/dist/resources/extensions/gsd/triage-resolution.js

@@ -13,7 +13,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { join } from "node:path";
 import { createRequire } from "node:module";
-import { gsdRoot, milestonesDir } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestonePath } from "./paths.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { loadAllCaptures, loadActionableCaptures, markCaptureExecuted, stampCaptureMilestone, } from "./captures.js";
 // ─── Resolution Executors ─────────────────────────────────────────────────────
@@ -149,8 +149,9 @@ export function executeBacktrack(basePath, currentMilestoneId, capture) {
         // so deriveState() will re-enter it as the active milestone.
         if (targetMilestoneId) {
             try {
-                const targetDir = join(milestonesDir(basePath), targetMilestoneId);
-                if (existsSync(targetDir)) {
+                // Use resolveMilestonePath to locate the dir in either legacy or flat-phase layout.
+                const targetDir = resolveMilestonePath(basePath, targetMilestoneId);
+                if (targetDir && existsSync(targetDir)) {
                     // Write a regression marker so the state machine knows this milestone
                     // needs re-discussion, not just re-execution
                     const regressionPath = join(targetDir, `${targetMilestoneId}-REGRESSION.md`);
@@ -270,9 +271,14 @@ export function detectFileOverlap(affectedFiles, planContent) {
 export function ensureDeferMilestoneDir(basePath, targetMilestone, captures) {
     if (!MILESTONE_ID_RE.test(targetMilestone))
         return false;
-    const msDir = join(milestonesDir(basePath), targetMilestone);
-    if (existsSync(msDir))
+    // Check if the milestone dir already exists in either layout.
+    const existingDir = resolveMilestonePath(basePath, targetMilestone);
+    if (existingDir && existsSync(existingDir))
         return true;
+    // Create new dir in the layout-appropriate location.
+    const legacyBase = legacyMilestonesDir(basePath);
+    const msBase = existsSync(legacyBase) ? legacyBase : milestonesDir(basePath);
+    const msDir = join(msBase, targetMilestone);
     try {
         mkdirSync(msDir, { recursive: true });
         // Seed CONTEXT-DRAFT.md with deferred capture context
@@ -389,8 +395,9 @@ export function executeTriageResolutions(basePath, mid, sid) {
             }
         }
         for (const [milestoneId, captures] of byMilestone) {
-            const msDir = join(milestonesDir(basePath), milestoneId);
-            if (!existsSync(msDir)) {
+            // Use resolveMilestonePath to check existence in either layout.
+            const existingMs = resolveMilestonePath(basePath, milestoneId);
+            if (!existingMs || !existsSync(existingMs)) {
                 const created = ensureDeferMilestoneDir(basePath, milestoneId, captures);
                 if (created) {
                     result.deferredMilestones++;

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

@@ -9,10 +9,11 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { parseUnitId } from "./unit-id.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
-import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveTaskFile, buildTaskFileName, buildSliceFileName } from "./paths.js";
+import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveSliceFile, resolveTaskFile, buildTaskFileName } from "./paths.js";
 import { sendDesktopNotification } from "./notifications.js";
 import { getTask, getSlice, getSliceTasks, updateTaskStatus, resetSliceCascade } from "./gsd-db.js";
 import { renderPlanCheckboxes, renderRoadmapCheckboxes } from "./markdown-renderer.js";
+import { UNIT_REGISTRY } from "./unit-registry.js";
 /**
  * Undo the last completed unit: revert git commits,
  * delete summary artifacts, and uncheck the task in PLAN.
@@ -35,15 +36,19 @@ export async function handleUndo(args, ctx, _pi, basePath) {
         ctx.ui.notify("Nothing to undo — no activity logs found.", "info");
         return;
     }
-    // Extract unit type and ID from the most recent activity log filename
-    // Format: <seq>-<unitType>-<unitId>.jsonl
-    const match = files[0].match(/^\d+-(.+?)-(.+)\.jsonl$/);
-    if (!match) {
+    // Extract unit type and ID from the most recent activity log filename.
+    // Both the unit type and the unit ID may contain hyphens, so anchor on the
+    // known unit-type vocabulary instead of guessing the unit-ID shape: a regex
+    // tuned to milestone-shaped IDs rejects project-level units whose IDs are
+    // symbolic (e.g. discuss-project uses PROJECT, workflow-preferences uses
+    // WORKFLOW-PREFS).
+    const parsed = parseActivityLogFilename(files[0]);
+    if (!parsed) {
         ctx.ui.notify("Nothing to undo — could not parse latest activity log.", "warning");
         return;
     }
-    const unitType = match[1];
-    const unitId = match[2].replace(/-/g, "/");
+    const unitType = parsed.unitType;
+    const unitId = parsed.unitId.replace(/-/g, "/");
     if (!force) {
         ctx.ui.notify(`Will undo: ${unitType} (${unitId})\n` +
             `This will:\n` +
@@ -87,6 +92,11 @@ export async function handleUndo(args, ctx, _pi, basePath) {
     if (unitType === "execute-task" && task !== undefined && slice !== undefined) {
         const [mid, sid, tid] = [milestone, slice, task];
         planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
+        if (getTask(mid, sid, tid)) {
+            updateTaskStatus(mid, sid, tid, "pending");
+            await renderPlanCheckboxes(basePath, mid, sid);
+            planUpdated = true;
+        }
     }
     // 3. Try to revert git commits from activity log
     let commitsReverted = 0;
@@ -291,15 +301,14 @@ export async function handleResetSlice(args, ctx, _pi, basePath) {
         }
     }
     // Delete slice summary and UAT files
+    // Use resolveSliceFile so the legacy S01-SUMMARY.md filename is found even
+    // when buildSliceFileName now returns the flat-phase 01-SUMMARY.md format.
     let sliceFilesDeleted = 0;
-    const slicePath = resolveSlicePath(basePath, mid, sid);
-    if (slicePath) {
-        for (const suffix of ["SUMMARY", "UAT"]) {
-            const filePath = join(slicePath, buildSliceFileName(sid, suffix));
-            if (existsSync(filePath)) {
-                unlinkSync(filePath);
-                sliceFilesDeleted++;
-            }
+    for (const suffix of ["SUMMARY", "UAT"]) {
+        const filePath = resolveSliceFile(basePath, mid, sid, suffix);
+        if (filePath && existsSync(filePath)) {
+            unlinkSync(filePath);
+            sliceFilesDeleted++;
         }
     }
     // Re-render plan + roadmap checkboxes
@@ -319,6 +328,33 @@ export async function handleResetSlice(args, ctx, _pi, basePath) {
     ctx.ui.notify(results.join("\n"), "success");
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────
+// Known unit types sorted longest-first so a more specific type (e.g.
+// "execute-task-simple") matches before a prefix of it ("execute-task") when
+// splitting "<seq>-<unitType>-<unitId>.jsonl".
+const UNIT_TYPES_BY_LENGTH_DESC = Object.keys(UNIT_REGISTRY).sort((a, b) => b.length - a.length);
+/**
+ * Parse an activity-log filename of the form `<seq>-<unitType>-<unitId>.jsonl`
+ * (the format written by activity-log.ts). Both the unit type and the unit ID
+ * may contain hyphens, so we anchor on the known unit-type vocabulary rather
+ * than guessing the ID shape. This keeps non-milestone IDs (e.g. PROJECT,
+ * WORKFLOW-PREFS) parseable. Returns null when the name has no sequence prefix
+ * or does not start with a recognised unit type.
+ */
+export function parseActivityLogFilename(filename) {
+    const seqMatch = filename.match(/^\d+-(.+)\.jsonl$/);
+    if (!seqMatch)
+        return null;
+    const rest = seqMatch[1];
+    for (const unitType of UNIT_TYPES_BY_LENGTH_DESC) {
+        const prefix = `${unitType}-`;
+        if (rest.startsWith(prefix)) {
+            const unitId = rest.slice(prefix.length);
+            if (unitId.length > 0)
+                return { unitType, unitId };
+        }
+    }
+    return null;
+}
 export function uncheckTaskInPlan(basePath, mid, sid, tid) {
     const slicePath = resolveSlicePath(basePath, mid, sid);
     if (!slicePath)

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

@@ -92,13 +92,27 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE = {
     orchestration: "Use `gsd_resume` before resuming orchestration, `gsd_exec_search` to reuse prior runs, and `gsd_exec` for noisy coordination checks.",
     docs: "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
-// Per-unit overrides win over the lane default. run-uat's tool contract
-// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
-// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
-// shared verification-lane guidance would steer the agent into calling an
-// unavailable tool.
-const CONTEXT_MODE_GUIDANCE_BY_UNIT = {
+// Per-unit overrides win over the lane default. Some units intentionally run
+// with narrower tool contracts than their shared Context Mode lane, so their
+// guidance must name only tools the unit can actually call.
+export const CONTEXT_MODE_GUIDANCE_BY_UNIT = {
+    "discuss-milestone": "Use `ask_user_questions` to continue the milestone interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, `gsd_requirement_save`, `gsd_requirement_update`, `gsd_plan_milestone`, or `gsd_milestone_generate_id` as appropriate.",
+    "discuss-slice": "Use `ask_user_questions` to continue the slice interview, then persist outcomes with `gsd_summary_save` or `gsd_decision_save` as appropriate.",
+    "discuss-project": "Use `ask_user_questions` to continue the project interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, or `gsd_requirement_save` as appropriate.",
+    "discuss-requirements": "Use `ask_user_questions` to continue the requirements interview, then persist outcomes with `gsd_requirement_save` or `gsd_summary_save` as appropriate.",
+    "replan-slice": "Use `gsd_replan_slice` to persist the revised slice plan, and `gsd_decision_save` for planning decisions that need durable rationale.",
+    "reassess-roadmap": "Use `gsd_milestone_status` to inspect current milestone state, then `gsd_reassess_roadmap` to persist the roadmap reassessment.",
     "run-uat": "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+    "research-project": "Dispatch parallel scout subagents for stack, features, architecture, and pitfalls research; each writes one file under `.gsd/research/` (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`).",
+    "gate-evaluate": "Use `subagent` to dispatch tester agents, then persist each gate with `gsd_save_gate_result`; rely on testers for verification evidence.",
+};
+// Per-unit guidance for the nested render mode (renderMode: "nested"), used when this
+// unit's Context Mode line is embedded into a subagent prompt — e.g. the tester prompts
+// dispatched by gate-evaluate. Must instruct the subagent on what IT should do, not
+// re-state the parent coordinator's dispatch instructions. Falls back to
+// CONTEXT_MODE_GUIDANCE_BY_UNIT then the lane default when no nested entry exists.
+export const CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT = {
+    "gate-evaluate": "Run verification checks to answer the gate question, then persist the verdict with `gsd_save_gate_result`.",
 };
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
@@ -112,7 +126,9 @@ export function composeContextModeInstructions(unitType, opts) {
     if (!manifest || manifest.contextMode === "none")
         return "";
     const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
-    const guidance = CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    const guidance = (opts.renderMode === "nested" ? CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT[unitType] : undefined)
+        ?? CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType]
+        ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
     if (opts.renderMode === "nested") {
         return `Context Mode (${lane} lane): ${guidance}`;
     }