gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

package/dist/resources/extensions/gsd/templates/PREFERENCES.md

@@ -39,6 +39,7 @@ dynamic_routing:
   budget_pressure:
   cross_provider:
   hooks:
+disabled_model_providers: []
 uok:
   enabled: true
   legacy_fallback:

package/dist/resources/extensions/gsd/templates/project.md

@@ -11,6 +11,16 @@
 
 {{theOneThingThatMustWorkEvenIfEverythingElseIsCut}}
 
+## Project Shape
+
+<!-- Drives questioning depth in downstream stages. `simple` → short plain-text
+     rounds, fast PROJECT/CONTEXT/REQUIREMENTS writes. `complex` → researched
+     3–4-option questions with an "Other — let me discuss" hatch.
+     Default to `complex` when uncertain. -->
+
+- **Complexity:** {{simple | complex}}
+- **Why:** {{one-line rationale citing the signals that decided it}}
+
 ## Current State
 
 {{whatHasBeenBuiltSoFar — what works, what exists, what's deployed}}

package/dist/resources/extensions/gsd/token-counter.js

@@ -1,5 +1,6 @@
 const CHARS_PER_TOKEN_BY_PROVIDER = {
     anthropic: 3.5,
+    "claude-code": 3.5,
     openai: 4.0,
     google: 4.0,
     mistral: 3.8,

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

@@ -145,16 +145,16 @@ export async function handleCompleteMilestone(params, basePath) {
     // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
     // completion already wrote the file. Overwriting would silently destroy the
     // richer content the agent produced during the original completion run.
+    let projectionStale = false;
     if (!existsSync(summaryPath)) {
         try {
             await saveFile(summaryPath, summaryMd);
         }
         catch (renderErr) {
-            // Disk render failed — roll back DB status so state stays consistent
-            logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${renderErr.message}`);
-            updateMilestoneStatus(params.milestoneId, 'active', null);
-            invalidateStateCache();
-            return { error: `disk render failed: ${renderErr.message}` };
+            projectionStale = true;
+            logWarning("projection", `complete_milestone projection write failed for ${params.milestoneId}; DB completion remains committed`, {
+                error: renderErr.message,
+            });
         }
     }
     // Invalidate all caches
@@ -192,5 +192,6 @@ export async function handleCompleteMilestone(params, basePath) {
     return {
         milestoneId: params.milestoneId,
         summaryPath,
+        ...(projectionStale ? { stale: true } : {}),
     };
 }

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

@@ -4,7 +4,8 @@
  * Validates inputs, checks all tasks are complete, writes slice row to DB in
  * a transaction, then (outside the transaction) renders SUMMARY.md + UAT.md
  * to disk, toggles the roadmap checkbox, stores rendered markdown in DB for
- * D004 recovery, and invalidates caches.
+ * D004 recovery, and invalidates caches. Projection write failures are stale
+ * projection diagnostics and do not roll back committed DB state.
  */
 import { join } from "node:path";
 import { mkdirSync } from "node:fs";
@@ -216,7 +217,6 @@ export async function handleCompleteSlice(params, basePath) {
     }
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     const completedAt = new Date().toISOString();
-    const originalSliceStatus = getSlice(params.milestoneId, params.sliceId)?.status ?? "pending";
     let guardError = null;
     transaction(() => {
         // State machine preconditions (inside txn for atomicity).
@@ -272,9 +272,6 @@ export async function handleCompleteSlice(params, basePath) {
     if (guardError) {
         return { error: guardError };
     }
-    // ── Filesystem operations (outside transaction) ─────────────────────────
-    // If disk render fails, roll back the DB status so deriveState() and
-    // verifyExpectedArtifact() stay consistent (both say "not done").
     // Render summary markdown
     const summaryMd = renderSliceSummaryMarkdown(params);
     // Resolve and write summary to disk
@@ -292,6 +289,8 @@ export async function handleCompleteSlice(params, basePath) {
     }
     const uatMd = renderUatMarkdown(params);
     const uatPath = summaryPath.replace(/-SUMMARY\.md$/, "-UAT.md");
+    setSliceSummaryMd(params.milestoneId, params.sliceId, summaryMd, uatMd);
+    let projectionStale = false;
     try {
         await saveFile(summaryPath, summaryMd);
         await saveFile(uatPath, uatMd);
@@ -302,14 +301,9 @@ export async function handleCompleteSlice(params, basePath) {
         }
     }
     catch (renderErr) {
-        // Disk render failed — roll back DB status so state stays consistent
-        logWarning("tool", `complete_slice — disk render failed for ${params.milestoneId}/${params.sliceId}, rolling back DB status`, { error: renderErr.message });
-        updateSliceStatus(params.milestoneId, params.sliceId, originalSliceStatus);
-        invalidateStateCache();
-        return { error: `disk render failed: ${renderErr.message}` };
+        projectionStale = true;
+        logWarning("projection", `complete_slice projection write failed for ${params.milestoneId}/${params.sliceId}; DB completion remains committed`, { error: renderErr.message });
     }
-    // Store rendered markdown in DB for D004 recovery
-    setSliceSummaryMd(params.milestoneId, params.sliceId, summaryMd, uatMd);
     // ── Close gates owned by complete-slice (Q8) ───────────────────────────
     // Each owned gate maps to a specific summary section via the registry.
     // If the caller populated the corresponding field, record `pass`; if the
@@ -400,5 +394,6 @@ export async function handleCompleteSlice(params, basePath) {
         milestoneId: params.milestoneId,
         summaryPath,
         uatPath,
+        ...(projectionStale ? { stale: true } : {}),
     };
 }

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

@@ -1,17 +1,17 @@
 /**
  * complete-task handler — the core operation behind gsd_complete_task.
  *
- * Validates inputs, writes task row to DB in a transaction, then (outside
- * the transaction) renders SUMMARY.md to disk, toggles the plan checkbox,
- * stores the rendered markdown in the DB for D004 recovery, and invalidates
- * caches.
+ * Validates inputs, writes task row and rendered SUMMARY.md to DB in a
+ * transaction, then renders projections to disk and invalidates caches.
+ * Projection write failures are reported as stale projections and do not roll
+ * back committed DB state.
  */
 import { join } from "node:path";
 import { mkdirSync } from "node:fs";
 import { isClosedStatus } from "../status-guards.js";
-import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, setTaskSummaryMd, deleteVerificationEvidence, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
+import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, deleteVerificationEvidence, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
 import { getGatesForTurn } from "../gate-registry.js";
-import { resolveSliceFile, resolveTasksDir, clearPathCache } from "../paths.js";
+import { resolveTasksDir, clearPathCache } from "../paths.js";
 import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
@@ -119,6 +119,7 @@ export async function handleCompleteTask(params, basePath) {
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     const completedAt = new Date().toISOString();
     let guardError = null;
+    let summaryMd = "";
     // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
     // Building the artifact runs the full shape validation (2-4 options, unique
     // ids, recommendation references a real id). If the payload is malformed
@@ -184,6 +185,8 @@ export async function handleCompleteTask(params, basePath) {
             return;
         }
         // All guards passed — perform writes
+        const taskRow = paramsToTaskRow(params, completedAt);
+        summaryMd = renderSummaryContent(taskRow, params.sliceId, params.milestoneId, params.verificationEvidence ?? []);
         insertMilestone({ id: params.milestoneId, title: params.milestoneId });
         insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId });
         insertTask({
@@ -201,6 +204,7 @@ export async function handleCompleteTask(params, basePath) {
             knownIssues: params.knownIssues ?? "None.",
             keyFiles: params.keyFiles ?? [],
             keyDecisions: params.keyDecisions ?? [],
+            fullSummaryMd: summaryMd,
         });
         for (const evidence of (params.verificationEvidence ?? [])) {
             insertVerificationEvidence({
@@ -235,12 +239,7 @@ export async function handleCompleteTask(params, basePath) {
     if (guardError) {
         return { error: guardError };
     }
-    // ── Filesystem operations (outside transaction) ─────────────────────────
-    // If disk render fails, roll back the DB status so deriveState() and
-    // verifyExpectedArtifact() stay consistent (both say "not done").
-    // Render summary markdown via the single source of truth (#2720)
-    const taskRow = paramsToTaskRow(params, completedAt);
-    const summaryMd = renderSummaryContent(taskRow, params.sliceId, params.milestoneId, params.verificationEvidence ?? []);
+    let projectionStale = false;
     // Resolve and write summary to disk
     let summaryPath;
     const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
@@ -256,28 +255,16 @@ export async function handleCompleteTask(params, basePath) {
     }
     try {
         await saveFile(summaryPath, summaryMd);
-        // Toggle plan checkbox via renderer module
-        const planPath = resolveSliceFile(basePath, params.milestoneId, params.sliceId, "PLAN");
-        if (planPath) {
-            await renderPlanCheckboxes(basePath, params.milestoneId, params.sliceId);
-        }
-        else {
-            process.stderr.write(`gsd-db: complete_task — could not find plan file for ${params.sliceId}/${params.milestoneId}, skipping checkbox toggle\n`);
-        }
+        // Toggle or regenerate the plan projection from DB. Missing projection
+        // files are rebuilt by the renderer instead of being skipped.
+        await renderPlanCheckboxes(basePath, params.milestoneId, params.sliceId);
     }
     catch (renderErr) {
-        // Disk render failed — roll back DB status so state stays consistent
-        logWarning("tool", `complete_task — disk render failed, rolling back DB status: ${renderErr.message}`);
-        // Delete orphaned verification_evidence rows first (FK constraint
-        // references tasks, so evidence must go before status change).
-        // Without this, retries accumulate duplicate evidence rows (#2724).
-        deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
-        updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
-        invalidateStateCache();
-        return { error: `disk render failed: ${renderErr.message}` };
+        projectionStale = true;
+        logWarning("projection", `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; DB completion remains committed`, {
+            error: renderErr.message,
+        });
     }
-    // Store rendered markdown in DB for D004 recovery
-    setTaskSummaryMd(params.milestoneId, params.sliceId, params.taskId, summaryMd);
     // ── Close gates owned by execute-task (Q5/Q6/Q7) for this task ────────
     // Each gate id maps to a specific params field via taskGateFieldForId.
     // When the model populates the field, record `pass`; when it's empty,
@@ -387,5 +374,6 @@ export async function handleCompleteTask(params, basePath) {
         sliceId: params.sliceId,
         milestoneId: params.milestoneId,
         summaryPath,
+        ...(projectionStale ? { stale: true } : {}),
     };
 }

package/dist/resources/extensions/gsd/tools/memory-tools.js

@@ -59,8 +59,25 @@ export function executeMemoryCapture(params) {
     const scope = normalizeScope(params.scope);
     const tags = normalizeTags(params.tags);
     const structuredFields = normalizeStructuredFields(params.structuredFields);
-    const id = createMemory({ category, content, confidence, scope, tags, structuredFields });
+    let id;
+    try {
+        id = createMemory({ category, content, confidence, scope, tags, structuredFields });
+    }
+    catch (err) {
+        // Surface the underlying SQL message (e.g. "database disk image is
+        // malformed", "no such table: memories") so the operator gets the
+        // actionable signal instead of an opaque "create_failed". See #4967.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: failed to create memory: ${message}` }],
+            details: { operation: "memory_capture", error: message },
+            isError: true,
+        };
+    }
     if (!id) {
+        // DB unavailable or adapter missing — distinct from the SQL-error path
+        // above. Keep the legacy create_failed token here so any consumers that
+        // explicitly key on the unavailable case continue to work.
         return {
             content: [{ type: "text", text: "Error: failed to create memory." }],
             details: { operation: "memory_capture", error: "create_failed" },

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

@@ -74,11 +74,12 @@ function validateParams(params) {
         throw new Error("goal is required");
     return {
         ...params,
-        // Apply defaults for optional enrichment fields (#2771)
-        successCriteria: params.successCriteria ?? "Not provided.",
-        proofLevel: params.proofLevel ?? "Not provided.",
-        integrationClosure: params.integrationClosure ?? "Not provided.",
-        observabilityImpact: params.observabilityImpact ?? "Not provided.",
+        // Keep optional enrichment fields empty when omitted. The renderer supplies
+        // conservative defaults where needed, without surfacing placeholder prose.
+        successCriteria: params.successCriteria ?? "",
+        proofLevel: params.proofLevel ?? "",
+        integrationClosure: params.integrationClosure ?? "",
+        observabilityImpact: params.observabilityImpact ?? "",
         tasks: validateTasks(params.tasks),
     };
 }

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

@@ -9,7 +9,7 @@
  * despite passing validation.
  */
 import { join } from "node:path";
-import { transaction, insertAssessment, deleteAssessmentByScope, getMilestoneSlices, } from "../gsd-db.js";
+import { transaction, insertAssessment, getMilestoneSlices, } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -99,14 +99,15 @@ export async function handleValidateMilestone(params, basePath, opts) {
         insertMilestoneValidationGates(params.milestoneId, gateSliceId, params.verdict, validatedAt);
     });
     // ── Filesystem render (outside transaction) ────────────────────────────
-    // If disk render fails, roll back the DB row so state stays consistent.
+    let projectionStale = false;
     try {
         await saveFile(validationPath, validationMd);
     }
     catch (renderErr) {
-        logWarning("tool", `validate_milestone — disk render failed, rolling back DB row: ${renderErr.message}`);
-        deleteAssessmentByScope(params.milestoneId, 'milestone-validation');
-        return { error: `disk render failed: ${renderErr.message}` };
+        projectionStale = true;
+        logWarning("projection", `validate_milestone projection write failed for ${params.milestoneId}; DB validation remains committed`, {
+            error: renderErr.message,
+        });
     }
     invalidateStateCache();
     clearPathCache();
@@ -147,5 +148,6 @@ export async function handleValidateMilestone(params, basePath, opts) {
         milestoneId: params.milestoneId,
         verdict: params.verdict,
         validationPath,
+        ...(projectionStale ? { stale: true } : {}),
     };
 }

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

@@ -1,9 +1,9 @@
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js";
-import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
-import { getMilestone, getSliceStatusSummary, getSliceTaskCounts, readTransaction, saveGateResult, } from "../gsd-db.js";
+import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
+import { getActiveRequirements, getMilestone, getSliceStatusSummary, getSliceTaskCounts, readTransaction, saveGateResult, } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
-import { saveArtifactToDb } from "../db-writer.js";
+import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
 import { resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { unlinkSync } from "node:fs";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -16,10 +16,27 @@ import { handleReassessRoadmap } from "./reassess-roadmap.js";
 import { handleValidateMilestone } from "./validate-milestone.js";
 import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
-export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT"];
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
+    "SUMMARY",
+    "RESEARCH",
+    "CONTEXT",
+    "ASSESSMENT",
+    "CONTEXT-DRAFT",
+    "PROJECT",
+    "PROJECT-DRAFT",
+    "REQUIREMENTS",
+    "REQUIREMENTS-DRAFT",
+];
 export function isSupportedSummaryArtifactType(artifactType) {
     return SUPPORTED_SUMMARY_ARTIFACT_TYPES.includes(artifactType);
 }
+function isRootSummaryArtifactType(artifactType) {
+    return artifactType === "PROJECT" ||
+        artifactType === "PROJECT-DRAFT" ||
+        artifactType === "REQUIREMENTS" ||
+        artifactType === "REQUIREMENTS-DRAFT";
+}
 export async function executeSummarySave(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
@@ -36,7 +53,24 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
             isError: true,
         };
     }
-    const contextGuard = shouldBlockContextArtifactSaveInSnapshot(loadWriteGateSnapshot(basePath), params.artifact_type, params.milestone_id ?? null, params.slice_id ?? null);
+    if (!isRootSummaryArtifactType(params.artifact_type) && !params.milestone_id) {
+        return {
+            content: [{ type: "text", text: `Error: milestone_id is required for artifact_type "${params.artifact_type}". Root-level artifacts must use PROJECT, PROJECT-DRAFT, REQUIREMENTS, or REQUIREMENTS-DRAFT.` }],
+            details: { operation: "save_summary", error: "missing_milestone_id" },
+            isError: true,
+        };
+    }
+    const writeGateSnapshot = loadWriteGateSnapshot(basePath);
+    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
+    const rootArtifactGuard = shouldBlockRootArtifactSaveInSnapshot(writeGateSnapshot, params.artifact_type, { requireVerifiedApproval: prefs?.planning_depth === "deep" });
+    if (rootArtifactGuard.block) {
+        return {
+            content: [{ type: "text", text: `Error saving artifact: ${rootArtifactGuard.reason ?? "root artifact write blocked"}` }],
+            details: { operation: "save_summary", error: "root_artifact_write_blocked" },
+            isError: true,
+        };
+    }
+    const contextGuard = shouldBlockContextArtifactSaveInSnapshot(writeGateSnapshot, params.artifact_type, params.milestone_id ?? null, params.slice_id ?? null);
     if (contextGuard.block) {
         return {
             content: [{ type: "text", text: `Error saving artifact: ${contextGuard.reason ?? "context write blocked"}` }],
@@ -46,7 +80,19 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
     }
     try {
         let relativePath;
-        if (params.task_id && params.slice_id) {
+        if (params.artifact_type === "PROJECT") {
+            relativePath = "PROJECT.md";
+        }
+        else if (params.artifact_type === "PROJECT-DRAFT") {
+            relativePath = "PROJECT-DRAFT.md";
+        }
+        else if (params.artifact_type === "REQUIREMENTS") {
+            relativePath = "REQUIREMENTS.md";
+        }
+        else if (params.artifact_type === "REQUIREMENTS-DRAFT") {
+            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`;
         }
         else if (params.slice_id) {
@@ -55,13 +101,30 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
         else {
             relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
         }
+        const activeRequirements = params.artifact_type === "REQUIREMENTS"
+            ? getActiveRequirements()
+            : null;
+        if (params.artifact_type === "REQUIREMENTS" && activeRequirements?.length === 0) {
+            return {
+                content: [{ type: "text", text: "Error: Cannot save REQUIREMENTS artifact — no active requirements found in the database. Call gsd_requirement_save for each requirement before calling gsd_summary_save(REQUIREMENTS)." }],
+                details: { operation: "save_summary", error: "no_active_requirements" },
+                isError: true,
+            };
+        }
+        const contentToSave = params.artifact_type === "REQUIREMENTS"
+            ? generateRequirementsMd(activeRequirements ?? [])
+            : params.content;
+        const contentSource = params.artifact_type === "REQUIREMENTS"
+            ? "requirements_table"
+            : "provided_content";
+        const isRootArtifact = isRootSummaryArtifactType(params.artifact_type);
         await saveArtifactToDb({
             path: relativePath,
             artifact_type: params.artifact_type,
-            content: params.content,
-            milestone_id: params.milestone_id,
-            slice_id: params.slice_id,
-            task_id: params.task_id,
+            content: contentToSave,
+            milestone_id: isRootArtifact ? undefined : params.milestone_id,
+            slice_id: isRootArtifact ? undefined : params.slice_id,
+            task_id: isRootArtifact ? undefined : params.task_id,
         }, basePath);
         if (params.artifact_type === "CONTEXT" && !params.task_id) {
             try {
@@ -77,7 +140,7 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
         }
         return {
             content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
-            details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },
+            details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type, content_source: contentSource },
         };
     }
     catch (err) {

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

@@ -73,6 +73,18 @@ const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
 // allowed-path set for the docs policy lives in one reviewable place.
 const TOOLS_ALL = { mode: "all" };
 const TOOLS_PLANNING = { mode: "planning" };
+// Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
+// specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
+const TOOLS_PLANNING_DISPATCH_RECON = {
+    mode: "planning-dispatch",
+    allowedSubagents: ["scout", "planner"],
+};
+// Like TOOLS_PLANNING_DISPATCH_RECON, but for closeout units that fan out
+// verification work to review-tier specialists.
+const TOOLS_PLANNING_DISPATCH_REVIEW = {
+    mode: "planning-dispatch",
+    allowedSubagents: ["reviewer", "security", "tester"],
+};
 const TOOLS_DOCS = {
     mode: "docs",
     // Globs are resolved relative to project basePath. The set is intentionally
@@ -110,6 +122,12 @@ export const KNOWN_UNIT_TYPES = [
     "run-uat",
     "gate-evaluate",
     "rewrite-docs",
+    // Deep planning mode (project-level) units
+    "workflow-preferences",
+    "discuss-project",
+    "discuss-requirements",
+    "research-decision",
+    "research-project",
 ];
 export const UNIT_MANIFESTS = {
     // ─── Milestone-scoped ────────────────────────────────────────────────
@@ -163,7 +181,11 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: false,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // planning-dispatch: validation is a verification-fan-out unit. It reads
+        // the milestone surface and dispatches reviewer/security/tester subagents
+        // to report findings without touching user source. Mirrors
+        // complete-milestone's policy. Write isolation to .gsd/ is preserved.
+        tools: TOOLS_PLANNING_DISPATCH_REVIEW,
         artifacts: {
             inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
             excerpt: [],
@@ -177,7 +199,11 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: false,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // planning-dispatch: completion is a high-leverage place to fan out to
+        // reviewer / security / tester subagents. They read the diff and report
+        // findings; they do not write user source. Write isolation to .gsd/ is
+        // preserved.
+        tools: TOOLS_PLANNING_DISPATCH_REVIEW,
         artifacts: {
             // #4780 landed slice-summary as excerpt for this unit; phase 2 of
             // the architecture will read this manifest as the source of truth
@@ -209,7 +235,10 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: true,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // planning-dispatch: allows subagent dispatch so the planner can fan out
+        // to scout for codebase recon and to planner/decompose-style specialists
+        // for sub-decomposition. Write-isolation to .gsd/ is preserved.
+        tools: TOOLS_PLANNING_DISPATCH_RECON,
         artifacts: {
             inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
             excerpt: [],
@@ -223,7 +252,10 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: true,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // See plan-slice — same rationale: dispatch to scout/planner-style
+        // specialists during refinement is materially better than re-doing recon
+        // inline.
+        tools: TOOLS_PLANNING_DISPATCH_RECON,
         artifacts: {
             inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
             excerpt: [],
@@ -251,7 +283,10 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: false,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // See complete-milestone — same rationale: dispatch to reviewer / security /
+        // tester subagents to fan out review work without bloating this unit's
+        // context.
+        tools: TOOLS_PLANNING_DISPATCH_REVIEW,
         artifacts: {
             // Phase 3 migration (#4782): matches today's actual
             // buildCompleteSlicePrompt inlining order. Overrides prepend +
@@ -356,6 +391,91 @@ export const UNIT_MANIFESTS = {
         },
         maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
     },
+    // ─── Deep planning mode (project-level) units ────────────────────────
+    // workflow-preferences: default-writing stage that records
+    // commit_policy / branch_model in PREFERENCES.md, defaults
+    // uat_dispatch/executor_class, and records the research decision. No project artifacts needed.
+    "workflow-preferences": {
+        skills: { mode: "none" },
+        knowledge: "none",
+        memory: "none",
+        codebaseMap: false,
+        preferences: "none",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: [],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    // discuss-project: PROJECT.md interview (deep mode only). Project-scoped
+    // discussion runs before any milestone exists, so milestone artifacts are
+    // not loaded. Keeps templates available for PROJECT.md scaffolding.
+    "discuss-project": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // discuss-requirements: REQUIREMENTS.md interview. PROJECT.md is the
+    // primary context input; templates carry the requirements format.
+    "discuss-requirements": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["project", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // research-decision: lightweight one-question yes/no unit. Writes a
+    // marker JSON; no project artifacts needed.
+    "research-decision": {
+        skills: { mode: "none" },
+        knowledge: "none",
+        memory: "none",
+        codebaseMap: false,
+        preferences: "none",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: [],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    // research-project: orchestrator that fans out 4 parallel scout subagents
+    // for project research (stack, features, architecture, pitfalls). Needs the
+    // planning-dispatch policy to dispatch them. PROJECT.md + REQUIREMENTS.md
+    // give the orchestrator the framing context.
+    "research-project": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: { mode: "planning-dispatch", allowedSubagents: ["scout"] },
+        artifacts: {
+            inline: ["project", "requirements", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
 };
 // ─── Lookup helper ────────────────────────────────────────────────────────
 /**