gsd-pi 2.78.1-dev.82bcf6b71 → 2.78.1-dev.84c045fd2

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/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

@@ -122,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 ────────────────────────────────────────────────
@@ -175,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: [],
@@ -381,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 ────────────────────────────────────────────────────────
 /**

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

@@ -1,8 +1,72 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
 import { gsdRoot, relSliceFile, relTaskFile, resolveSliceFile, resolveTaskFile, } from "./paths.js";
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseUnitId } from "./unit-id.js";
+// Per-record advisory lock — prevents read-modify-write races between
+// concurrent writers updating disjoint fields of the same runtime record.
+// Within a single Node process this is moot (writeUnitRuntimeRecord is sync),
+// but cross-process callers (parallel slice executors, doctor --fix while a
+// detached auto-mode session is alive) can otherwise clobber each other.
+const RECORD_LOCK_TIMEOUT_MS = 2_000;
+const RECORD_LOCK_STALE_MS = 5_000;
+const RECORD_LOCK_SLEEP_BUFFER = new SharedArrayBuffer(4);
+const RECORD_LOCK_SLEEP_VIEW = new Int32Array(RECORD_LOCK_SLEEP_BUFFER);
+function withRecordLock(recordPath, fn) {
+    const lockPath = recordPath + ".lock";
+    try {
+        mkdirSync(dirname(lockPath), { recursive: true });
+    }
+    catch {
+        // best-effort
+    }
+    const deadline = Date.now() + RECORD_LOCK_TIMEOUT_MS;
+    while (true) {
+        try {
+            // O_EXCL atomic create-if-not-exists.
+            closeSync(openSync(lockPath, "wx"));
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // Existing lock — check for staleness before either waiting or stealing.
+            try {
+                const stat = statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > RECORD_LOCK_STALE_MS) {
+                    try {
+                        unlinkSync(lockPath);
+                    }
+                    catch { /* race: already removed */ }
+                    continue;
+                }
+            }
+            catch {
+                // stat failed (file removed between EEXIST and stat) — retry create.
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                // Last-resort steal — unlikely in practice but avoids permanent wedge.
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch { /* race */ }
+                continue;
+            }
+            Atomics.wait(RECORD_LOCK_SLEEP_VIEW, 0, 0, 5);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* best-effort */ }
+    }
+}
 function runtimeDir(basePath) {
     return join(gsdRoot(basePath), "runtime", "units");
 }
@@ -12,29 +76,29 @@ function runtimePath(basePath, unitType, unitId) {
     return join(runtimeDir(basePath), `${sanitizedUnitType}-${sanitizedUnitId}.json`);
 }
 export function writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, updates = {}) {
-    const dir = runtimeDir(basePath);
-    mkdirSync(dir, { recursive: true });
     const path = runtimePath(basePath, unitType, unitId);
-    const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
-    const next = {
-        version: 1,
-        unitType,
-        unitId,
-        startedAt,
-        updatedAt: Date.now(),
-        phase: updates.phase ?? prev?.phase ?? "dispatched",
-        wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
-        continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
-        timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
-        lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
-        progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
-        lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
-        recovery: updates.recovery ?? prev?.recovery,
-        recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
-        lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
-    };
-    writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
-    return next;
+    return withRecordLock(path, () => {
+        const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+        const next = {
+            version: 1,
+            unitType,
+            unitId,
+            startedAt,
+            updatedAt: Date.now(),
+            phase: updates.phase ?? prev?.phase ?? "dispatched",
+            wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+            continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
+            timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+            lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+            progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+            lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+            recovery: updates.recovery ?? prev?.recovery,
+            recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+            lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+        };
+        atomicWriteSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+        return next;
+    });
 }
 export function readUnitRuntimeRecord(basePath, unitType, unitId) {
     const path = runtimePath(basePath, unitType, unitId);