gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

package/dist/resources/extensions/gsd/commands-ship.js

@@ -6,11 +6,13 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { deriveState } from "./state.js";
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile } from "./paths.js";
 import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bridge.js";
 import { formatDuration } from "../shared/format-utils.js";
+import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -68,6 +70,48 @@ function collectSliceSummaries(basePath, milestoneId) {
     }
     return summaries;
 }
+/**
+ * Inspect a single slice's EVAL-REVIEW.md without throwing.
+ *
+ * One async file read attempt — no `existsSync` precheck (defense against the
+ * TOCTOU race that bit prior implementations). ENOENT is treated as `absent`.
+ * Other read errors
+ * propagate so callers can decide how to handle them; the {@link handleShip}
+ * caller wraps them in a non-blocking warning rather than aborting the
+ * ship.
+ *
+ * @param basePath - project root.
+ * @param milestoneId - active milestone ID.
+ * @param sliceId - slice ID to check.
+ * @returns A {@link SliceEvalCheck} discriminating on the four valid states.
+ * @throws Forwarded `readFile` errors other than `ENOENT`.
+ */
+export async function checkSliceEvalReview(basePath, milestoneId, sliceId) {
+    const path = resolveSliceFile(basePath, milestoneId, sliceId, "EVAL-REVIEW");
+    if (!path) {
+        return { sliceId, kind: "absent" };
+    }
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { sliceId, kind: "absent" };
+        }
+        throw err;
+    }
+    const parsed = parseEvalReviewFrontmatter(raw);
+    if (!parsed.ok) {
+        return { sliceId, kind: "malformed", error: parsed.error, pointer: parsed.pointer };
+    }
+    return {
+        sliceId,
+        kind: "ok",
+        verdict: parsed.data.verdict,
+        overall_score: parsed.data.overall_score,
+    };
+}
 function generatePRContent(basePath, milestoneId, milestoneTitle) {
     const title = `feat: ${milestoneTitle || milestoneId}`;
     const sections = [];
@@ -154,6 +198,27 @@ export async function handleShip(args, ctx, _pi) {
         ctx.ui.notify(`Milestone ${milestoneId} may not be complete (phase: ${state.phase}). Use --force to ship anyway.`, "warning");
         return;
     }
+    // 2b. Pre-ship soft warning on EVAL-REVIEW.md status (non-blocking).
+    for (const sliceId of listSliceIds(basePath, milestoneId)) {
+        let result;
+        try {
+            result = await checkSliceEvalReview(basePath, milestoneId, sliceId);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Could not read EVAL-REVIEW.md for ${sliceId}: ${msg}`, "warning");
+            continue;
+        }
+        if (result.kind === "absent") {
+            ctx.ui.notify(`Slice ${sliceId} has no EVAL-REVIEW.md — consider /gsd eval-review ${sliceId} (non-blocking).`, "warning");
+        }
+        else if (result.kind === "malformed") {
+            ctx.ui.notify(`Slice ${sliceId} EVAL-REVIEW.md frontmatter invalid at ${result.pointer}: ${result.error} (non-blocking).`, "warning");
+        }
+        else if (result.verdict === "NOT_IMPLEMENTED") {
+            ctx.ui.notify(`Slice ${sliceId} eval verdict NOT_IMPLEMENTED (overall ${result.overall_score}/100) — shipping anyway, but the eval gap is unresolved.`, "warning");
+        }
+    }
     // 3. Generate PR content
     const { title, body } = generatePRContent(basePath, milestoneId, milestoneTitle);
     // 4. Dry-run — just show the PR content

package/dist/resources/extensions/gsd/context-budget.js

@@ -21,6 +21,8 @@ const VERIFICATION_RATIO = 0.10;
 const CHARS_PER_TOKEN = 4;
 /** Default context window when none can be resolved (D002) */
 const DEFAULT_CONTEXT_WINDOW = 200_000;
+/** Conservative effective context for Claude Code subscription routing (#4676) */
+const CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW = 200_000;
 /** Percentage of context consumed before suggesting a continue-here checkpoint */
 const CONTINUE_THRESHOLD_PERCENT = 70;
 // ─── Task count bounds ───────────────────────────────────────────────────────
@@ -109,7 +111,7 @@ export function truncateAtSectionBoundary(content, budgetChars) {
  *
  * Supports "provider/model" format in preferences for explicit provider targeting.
  */
-export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow) {
+export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow, sessionProvider) {
     // Step 1: Try configured executor model
     if (preferences?.models?.execution && registry) {
         const executionConfig = preferences.models.execution;
@@ -119,13 +121,13 @@ export function resolveExecutorContextWindow(registry, preferences, sessionConte
         if (modelId) {
             const model = findModelById(registry, modelId);
             if (model && model.contextWindow > 0) {
-                return model.contextWindow;
+                return resolveEffectiveContextWindow(model.contextWindow, model.provider);
             }
         }
     }
     // Step 2: Fall back to session context window
     if (sessionContextWindow && sessionContextWindow > 0) {
-        return sessionContextWindow;
+        return resolveEffectiveContextWindow(sessionContextWindow, sessionProvider);
     }
     // Step 3: Fall back to default (D002)
     return DEFAULT_CONTEXT_WINDOW;
@@ -151,6 +153,12 @@ function resolveTaskCountMax(contextWindow) {
     }
     return 3; // fallback — unreachable given tiers include 0
 }
+function resolveEffectiveContextWindow(contextWindow, provider) {
+    if (provider?.toLowerCase() === "claude-code" && contextWindow > CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW) {
+        return CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW;
+    }
+    return contextWindow;
+}
 /**
  * Split content into sections at `### ` headings or `---` dividers.
  * Each section includes its leading marker.

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

@@ -108,9 +108,9 @@ const STATUS_SECTION_MAP = [
 /**
  * Generate full REQUIREMENTS.md content from an array of Requirement objects.
  * Groups requirements by status into sections (## Active, ## Validated, etc.),
- * each containing ### RXXX — Description headings with bullet fields.
- * Only emits sections that have content. Appends Traceability table and
- * Coverage Summary at the bottom.
+ * each containing ### RXXX — Description headings with bullet fields. Empty
+ * status sections are emitted too because the deep-mode validator treats their
+ * presence as part of the canonical contract.
  */
 export function generateRequirementsMd(requirements) {
     const lines = [];
@@ -129,11 +129,9 @@ export function generateRequirementsMd(requirements) {
     // Emit sections in canonical order
     for (const { status, heading } of STATUS_SECTION_MAP) {
         const reqs = byStatus.get(status);
-        if (!reqs || reqs.length === 0)
-            continue;
         lines.push(`## ${heading}`);
         lines.push('');
-        for (const r of reqs) {
+        for (const r of reqs ?? []) {
             lines.push(`### ${r.id} — ${r.description || 'Untitled'}`);
             // Emit bullet fields — only those with content
             if (r.class)
@@ -179,6 +177,12 @@ export function generateRequirementsMd(requirements) {
     lines.push(`- Unmapped active requirements: 0`);
     return lines.join('\n') + '\n';
 }
+function isRootCanonicalArtifact(opts) {
+    if (opts.milestone_id || opts.slice_id || opts.task_id)
+        return false;
+    return (opts.artifact_type === 'PROJECT' ||
+        opts.artifact_type === 'REQUIREMENTS');
+}
 // ─── Next Decision ID ─────────────────────────────────────────────────────
 /**
  * Compute the next decision ID from the current DB state.
@@ -257,34 +261,61 @@ export async function saveRequirementToDb(fields, basePath) {
     try {
         const db = await import('./gsd-db.js');
         // Atomic ID assignment + insert inside a transaction.
-        const id = db.transaction(() => {
+        const txResult = db.transaction(() => {
             const adapter = db._getAdapter();
             if (!adapter)
                 throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+            const existingRow = adapter
+                .prepare(`SELECT * FROM requirements
+           WHERE LOWER(TRIM(description)) = LOWER(TRIM(:description))
+             AND LOWER(COALESCE(status, 'active')) = 'active'
+             AND superseded_by IS NULL
+           ORDER BY id
+           LIMIT 1`)
+                .get({ ':description': fields.description });
+            const previousRow = existingRow
+                ? {
+                    id: existingRow['id'],
+                    class: existingRow['class'],
+                    status: existingRow['status'],
+                    description: existingRow['description'],
+                    why: existingRow['why'],
+                    source: existingRow['source'],
+                    primary_owner: existingRow['primary_owner'],
+                    supporting_slices: existingRow['supporting_slices'],
+                    validation: existingRow['validation'],
+                    notes: existingRow['notes'],
+                    full_content: existingRow['full_content'],
+                    superseded_by: existingRow['superseded_by'] ?? null,
+                }
+                : null;
             const row = adapter
                 .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
                 .get();
             const maxNum = row ? row['max_num'] : null;
-            const nextId = (maxNum == null || isNaN(maxNum))
-                ? 'R001'
-                : `R${String(maxNum + 1).padStart(3, '0')}`;
+            const nextId = existingRow
+                ? String(existingRow['id'])
+                : (maxNum == null || isNaN(maxNum))
+                    ? 'R001'
+                    : `R${String(maxNum + 1).padStart(3, '0')}`;
             const requirement = {
                 id: nextId,
-                class: fields.class,
-                status: fields.status ?? 'active',
+                class: fields.class || existingRow?.['class'] || '',
+                status: fields.status ?? existingRow?.['status'] ?? 'active',
                 description: fields.description,
                 why: fields.why,
                 source: fields.source,
-                primary_owner: fields.primary_owner ?? '',
-                supporting_slices: fields.supporting_slices ?? '',
-                validation: fields.validation ?? '',
-                notes: fields.notes ?? '',
-                full_content: '',
-                superseded_by: null,
+                primary_owner: fields.primary_owner ?? existingRow?.['primary_owner'] ?? '',
+                supporting_slices: fields.supporting_slices ?? existingRow?.['supporting_slices'] ?? '',
+                validation: fields.validation ?? existingRow?.['validation'] ?? '',
+                notes: fields.notes ?? existingRow?.['notes'] ?? '',
+                full_content: existingRow?.['full_content'] ?? '',
+                superseded_by: existingRow?.['superseded_by'] ?? null,
             };
             db.upsertRequirement(requirement);
-            return nextId;
+            return { id: nextId, isNew: !existingRow, previousRow };
         });
+        const { id, isNew, previousRow } = txResult;
         // Fetch all requirements for full file regeneration
         const adapter = db._getAdapter();
         let allRequirements = [];
@@ -314,7 +345,12 @@ export async function saveRequirementToDb(fields, basePath) {
         catch (diskErr) {
             logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String(diskErr.message) });
             try {
-                db.deleteRequirementById(id);
+                if (isNew) {
+                    db.deleteRequirementById(id);
+                }
+                else if (previousRow) {
+                    db.upsertRequirement(previousRow);
+                }
             }
             catch (rollbackErr) {
                 logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String(rollbackErr.message) });
@@ -657,14 +693,25 @@ export async function saveArtifactToDb(opts, basePath) {
         if (!fullPath.startsWith(gsdDir)) {
             throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
         }
+        let contentToPersist = opts.content;
+        if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
+            const activeRequirements = db.getActiveRequirements();
+            if (activeRequirements.length === 0) {
+                throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDb: REQUIREMENTS final save requires active DB-backed requirements');
+            }
+            contentToPersist = generateRequirementsMd(activeRequirements);
+        }
         // Shrinkage guard: if the file already exists and the new content is
         // significantly smaller (<50%), preserve the richer file on disk and
-        // store its content in the DB instead of the abbreviated version.
-        let dbContent = opts.content;
+        // store its content in the DB instead of the abbreviated version. Root
+        // canonical artifacts are exempt because their content is rendered from
+        // canonical DB state, and cleanup/consolidation is often intentionally much
+        // smaller than a malformed accumulated file.
+        let dbContent = contentToPersist;
         let skipDiskWrite = false;
-        if (existsSync(fullPath)) {
+        if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
             const existingSize = statSync(fullPath).size;
-            const newSize = Buffer.byteLength(opts.content, 'utf-8');
+            const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
             if (existingSize > 0 && newSize < existingSize * 0.5) {
                 logWarning('manifest', `new content (${newSize}B) is <50% of existing file (${existingSize}B), preserving disk file`, { fn: 'saveArtifactToDb', path: opts.path });
                 dbContent = readFileSync(fullPath, 'utf-8');
@@ -682,7 +729,7 @@ export async function saveArtifactToDb(opts, basePath) {
         // Write the file to disk (only if we're not preserving a richer existing file)
         if (!skipDiskWrite) {
             try {
-                await saveFile(fullPath, opts.content);
+                await saveFile(fullPath, contentToPersist);
             }
             catch (diskErr) {
                 logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String(diskErr.message) });

package/dist/resources/extensions/gsd/deep-project-setup-policy.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { clearParseCache } from "./files.js";
+import { gsdRoot, clearPathCache } from "./paths.js";
+import { validateArtifact } from "./schemas/validate.js";
+import { getProjectResearchStatus } from "./project-research-policy.js";
+const EXPLICIT_RESEARCH_SOURCES = new Set([
+    "research-decision",
+    "user",
+]);
+function clearCaches() {
+    clearPathCache();
+    clearParseCache();
+}
+function runtimeDir(basePath) {
+    return join(gsdRoot(basePath), "runtime");
+}
+export function researchDecisionPath(basePath) {
+    return join(runtimeDir(basePath), "research-decision.json");
+}
+export function isWorkflowPrefsCaptured(basePath) {
+    const prefsPath = join(gsdRoot(basePath), "PREFERENCES.md");
+    if (!existsSync(prefsPath))
+        return false;
+    let content;
+    try {
+        content = readFileSync(prefsPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return false;
+    return /^workflow_prefs_captured:\s*true\s*$/m.test(match[1]);
+}
+export function writeDefaultResearchSkipDecision(basePath, reason = "deterministic-default", previousSource) {
+    mkdirSync(runtimeDir(basePath), { recursive: true });
+    const payload = {
+        decision: "skip",
+        decided_at: new Date().toISOString(),
+        source: "workflow-preferences",
+        reason,
+    };
+    if (previousSource)
+        payload.previous_source = previousSource;
+    writeFileSync(researchDecisionPath(basePath), `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+    clearCaches();
+}
+function readDecision(basePath) {
+    const path = researchDecisionPath(basePath);
+    if (!existsSync(path))
+        return { exists: false, valid: false };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        const decision = parsed.decision === "research" || parsed.decision === "skip"
+            ? parsed.decision
+            : undefined;
+        return {
+            exists: true,
+            valid: decision !== undefined,
+            decision,
+            source: typeof parsed.source === "string" ? parsed.source : undefined,
+        };
+    }
+    catch {
+        return { exists: true, valid: false };
+    }
+}
+function isExplicitResearchDecision(decision) {
+    return decision.decision === "research" && EXPLICIT_RESEARCH_SOURCES.has(decision.source);
+}
+export function resolveDeepProjectSetupState(prefs, basePath) {
+    if (prefs?.planning_depth !== "deep") {
+        return {
+            status: "not-applicable",
+            stage: null,
+            reason: "Deep planning mode is not enabled.",
+        };
+    }
+    const root = gsdRoot(basePath);
+    if (!isWorkflowPrefsCaptured(basePath)) {
+        return {
+            status: "pending",
+            stage: "workflow-preferences",
+            reason: ".gsd/PREFERENCES.md is missing workflow_prefs_captured: true.",
+        };
+    }
+    const projectPath = join(root, "PROJECT.md");
+    if (!existsSync(projectPath)) {
+        return {
+            status: "pending",
+            stage: "project",
+            reason: ".gsd/PROJECT.md is missing.",
+        };
+    }
+    if (!validateArtifact(projectPath, "project").ok) {
+        return {
+            status: "pending",
+            stage: "project",
+            reason: ".gsd/PROJECT.md is invalid.",
+        };
+    }
+    const requirementsPath = join(root, "REQUIREMENTS.md");
+    if (!existsSync(requirementsPath)) {
+        return {
+            status: "pending",
+            stage: "requirements",
+            reason: ".gsd/REQUIREMENTS.md is missing.",
+        };
+    }
+    if (!validateArtifact(requirementsPath, "requirements").ok) {
+        return {
+            status: "pending",
+            stage: "requirements",
+            reason: ".gsd/REQUIREMENTS.md is invalid.",
+        };
+    }
+    const marker = readDecision(basePath);
+    if (!marker.exists) {
+        writeDefaultResearchSkipDecision(basePath, "missing-default-repair");
+        return {
+            status: "complete",
+            stage: null,
+            reason: "Project research is skipped by the deterministic default.",
+        };
+    }
+    if (!marker.valid) {
+        writeDefaultResearchSkipDecision(basePath, "malformed-default-repair");
+        return {
+            status: "complete",
+            stage: null,
+            reason: "Malformed project research decision was repaired to the deterministic skip default.",
+        };
+    }
+    if (marker.decision === "skip") {
+        return {
+            status: "complete",
+            stage: null,
+            reason: "Project research was skipped.",
+        };
+    }
+    if (!isExplicitResearchDecision(marker)) {
+        writeDefaultResearchSkipDecision(basePath, "legacy-workflow-research-default", marker.source);
+        return {
+            status: "complete",
+            stage: null,
+            reason: "Legacy workflow-defaulted project research was normalized to skip.",
+        };
+    }
+    const researchStatus = getProjectResearchStatus(basePath);
+    if (researchStatus.globalBlocker) {
+        return {
+            status: "blocked",
+            stage: "project-research",
+            reason: "Project research wrote PROJECT-RESEARCH-BLOCKER.md, so no verified research exists. Fix the blocker cause, delete the blocker, and rerun auto.",
+        };
+    }
+    if (researchStatus.allDimensionBlockers) {
+        return {
+            status: "blocked",
+            stage: "project-research",
+            reason: "Project research produced only dimension blocker files, so no usable research exists. Fix the blocker cause, delete the dimension blocker files in `.gsd/research/`, and rerun auto.",
+        };
+    }
+    if (!researchStatus.complete) {
+        return {
+            status: "pending",
+            stage: "project-research",
+            reason: researchStatus.missingDimensions.length > 0
+                ? `Project research is missing dimensions: ${researchStatus.missingDimensions.join(", ")}.`
+                : "Project research has not produced a verified research set.",
+        };
+    }
+    return {
+        status: "complete",
+        stage: null,
+        reason: "All deep project setup gates are complete.",
+    };
+}

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

@@ -9,7 +9,7 @@ import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, s
 import { dirname, join, parse as parsePath } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "./gsd-home.js";
 // ─── Project File Markers ───────────────────────────────────────────────────────
 export const PROJECT_FILES = [
     "package.json",
@@ -602,23 +602,23 @@ function detectVerificationCommands(basePath, detectedFiles, packageManager) {
  * Check if global GSD setup exists (has ~/.gsd/ with preferences).
  */
 export function hasGlobalSetup() {
-    return (existsSync(join(gsdHome, "PREFERENCES.md")) ||
-        existsSync(join(gsdHome, "preferences.md")));
+    return (existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+        existsSync(join(gsdHome(), "preferences.md")));
 }
 /**
  * Check if this is the very first time GSD has been used on this machine.
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch() {
-    if (!existsSync(gsdHome))
+    if (!existsSync(gsdHome()))
         return true;
     // If we have preferences, not first launch
-    if (existsSync(join(gsdHome, "PREFERENCES.md")) ||
-        existsSync(join(gsdHome, "preferences.md"))) {
+    if (existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+        existsSync(join(gsdHome(), "preferences.md"))) {
         return false;
     }
     // If we have auth.json, not first launch (onboarding.ts already ran)
-    if (existsSync(join(gsdHome, "agent", "auth.json")))
+    if (existsSync(join(gsdHome(), "agent", "auth.json")))
         return false;
     // Check legacy path too
     const legacyPath = join(homedir(), ".pi", "agent", "gsd-preferences.md");

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -87,7 +87,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   | `git.push_branches`    | `false`      | `true`       |
   | `git.pre_merge_check`  | `false`      | `true`       |
   | `git.merge_strategy`   | `"squash"`   | `"squash"`   |
-  | `git.isolation`        | `"worktree"` | `"worktree"` |
+  | `git.isolation`        | `"none"`     | `"none"`     |
   | `unique_milestone_ids` | `false`      | `true`       |
 
   Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
@@ -137,7 +137,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
-  - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
+  - `isolation`: `"none"`, `"worktree"`, or `"branch"` — controls auto-mode git isolation strategy. `"none"` works directly on the current branch with no worktree or milestone branch (default, ideal for step-mode with hot reloads); `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos). `worktree` requires a committed `HEAD`; in a zero-commit repo, GSD temporarily treats it as `none` until the first commit exists. Default: `"none"`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
   - `auto_pr`: boolean — automatically create a GitHub pull request after a milestone branch is merged. Requires `gh` CLI to be installed. Default: `false`.
@@ -159,6 +159,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
+- `planning_depth`: `"light"` or `"deep"` — controls project-level discovery before milestone planning. `"light"` is the default milestone discussion flow. `"deep"` runs workflow preferences, project discussion, requirements discussion, a research-decision gate, and optional project research before milestone planning. Enable it with `/gsd new-project --deep`, `/gsd new-milestone --deep`, or by setting `planning_depth: deep` in `.gsd/PREFERENCES.md`. Deep mode writes `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `.gsd/runtime/research-decision.json`, and, when research is approved, `.gsd/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md`.
+
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
   - `reassess_after_slice`: boolean — run a dedicated roadmap-reassessment unit after each completed slice. Default: `false` (per ADR-003 §4). The plan-slice agent for the next slice performs JIT reassessment via a prompt preamble at zero additional token cost; a dedicated reassess session is opt-in. Set to `true` (e.g. via the `burn-max` profile) if you want the explicit session.
@@ -302,7 +304,7 @@ mode: solo
 ---
 ```
 
-Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: false`.
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: false`.
 
 **Team — unique IDs, push branches, pre-merge checks:**
 
@@ -313,7 +315,7 @@ mode: team
 ---
 ```
 
-Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: true`.
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: true`.
 
 **Mode with overrides — team mode but with auto-push:**
 

package/dist/resources/extensions/gsd/doctor-providers.js

@@ -16,7 +16,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY } from "./key-manager.js";
-import { getHomeDir } from "./home-dir.js";
+import { homedir } from "node:os";
 // ── Provider routing constants ────────────────────────────────────────────────
 /**
  * Providers that use external CLI authentication (not API keys).
@@ -159,7 +159,7 @@ function isCliBinaryInPath(providerId) {
     return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 function modelsJsonPaths() {
-    const home = getHomeDir();
+    const home = homedir();
     return [
         join(home, ".gsd", "agent", "models.json"),
         // Keep parity with custom-provider discovery during auto bootstrap.