gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

package/dist/resources/extensions/gsd/prompts/guided-workflow-preferences.md

@@ -0,0 +1,68 @@
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory. For `.gsd` files in this prompt, use absolute paths rooted at `{{workingDirectory}}` instead of discovering them with `Glob`.
+
+Configure project workflow preferences. This stage runs ONCE per project, early in deep-mode bootstrap, before `discuss-project`. It applies a small set of recommended workflow defaults and persists them to the YAML frontmatter of `.gsd/PREFERENCES.md` (the same file the runtime reads its preferences from).
+
+This is a **default-writing** stage — do NOT ask the user questions. Write the recommended defaults, then end. No follow-ups, no research, no opinion.
+
+---
+
+## Stage Banner
+
+Print this banner verbatim in chat as your first action:
+
+• WORKFLOW PREFERENCES
+
+Then say: "Quick setup — applying recommended workflow defaults."
+
+---
+
+## Default Set
+
+Use these recommended defaults without asking:
+
+- `commit_policy: per-task` — atomic commit after every task; finest granularity, easiest to revert
+- `branch_model: single` — all work on current branch
+- `uat_dispatch: true` — verification runs automatically; failures pause execution
+- `models.executor_class: balanced` — sensible cost/quality default
+- `research: skip` — deterministic default; the dedicated research-decision stage can later switch to `research`
+
+---
+
+## Output
+
+Apply the defaults:
+
+1. Read `{{workingDirectory}}/.gsd/PREFERENCES.md` if it exists. The file is YAML frontmatter (between `---` lines) followed by an optional markdown body. Parse the existing frontmatter so you can preserve unrelated keys (e.g. `planning_depth`).
+2. Merge the defaults into the frontmatter under these keys, preserving any existing explicit value:
+   - top-level `commit_policy: per-task`
+   - top-level `branch_model: single`
+   - top-level `uat_dispatch: true`
+   - top-level `research: skip`
+   - nested `models.executor_class: balanced`
+3. Also set top-level `workflow_prefs_captured: true` — this is the single explicit marker the dispatch layer uses to know the wizard has run.
+4. Write `{{workingDirectory}}/.gsd/PREFERENCES.md` back with the merged frontmatter and the original body preserved unchanged. Frontmatter delimiters are exactly `---` on their own lines.
+5. Pre-seed the research decision so the standalone `research-decision` stage is a no-op if the user already answered here:
+   - Ensure `{{workingDirectory}}/.gsd/runtime/` exists.
+   - Write `{{workingDirectory}}/.gsd/runtime/research-decision.json`:
+     ```json
+     {
+       "decision": "skip",
+       "decided_at": "<ISO 8601 timestamp>",
+       "source": "workflow-preferences",
+       "reason": "deterministic-default"
+     }
+     ```
+   Use `"skip"` unless an existing valid `{{workingDirectory}}/.gsd/runtime/research-decision.json` explicitly says `"research"` with `"source": "research-decision"` or `"source": "user"`.
+6. Print a concise summary in chat: each key on its own line, format `key: value`. Include `commit_policy`, `branch_model`, `uat_dispatch`, `models.executor_class`, and `research` (matching the preserved or pre-seeded runtime research decision).
+7. Say exactly: `"Workflow preferences saved."` — nothing else.
+
+Do NOT write to `.gsd/config.json`; runtime preferences load from `PREFERENCES.md`.
+
+---
+
+## Critical rules
+
+- Do NOT ask any questions. Defaults only, write file, done.
+- Do NOT call `ask_user_questions`, `AskUserQuestion`, or any other interactive user-input tool in this stage.
+- Do NOT change any keys other than the frontmatter keys specified plus `workflow_prefs_captured`. Research is persisted to `.gsd/runtime/research-decision.json`, NOT to `phases.skip_research`.
+- Preserve existing explicit values for `commit_policy`, `branch_model`, `uat_dispatch`, and `models.executor_class`; only fill missing values with defaults.

package/dist/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -1,5 +1,7 @@
 # Parallel Slice Research
 
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
 You are dispatching parallel research agents for **{{sliceCount}} slices** in milestone **{{mid}} — {{midTitle}}**.
 
 ## Slices to Research

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -10,6 +10,12 @@ All relevant context has been preloaded below — start working immediately with
 
 {{inlinedContext}}
 
+## Already Planned? Soft Brake
+
+If `{{outputPath}}` already exists on disk with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call `gsd_plan_milestone` — its UPSERT would overwrite the existing plan with whatever you reconstruct, which is unsafe when you don't have the original decomposition reasoning. Skip directly to the ready phrase at the end of this prompt.
+
+If only the file exists (no DB rows) or only DB rows exist (no file), the prior write was incomplete — proceed with planning as normal so the tool reconciles both.
+
 ## Your Role in the Pipeline
 
 You are the first deep look at this milestone. You have full tool access — explore the codebase, look up docs, investigate technology choices. Your job is to understand the landscape and then strategically decompose the work into demoable slices.
@@ -23,7 +29,7 @@ Before decomposing, build your understanding:
 1. **Codebase exploration.** For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 2. **Library docs.** Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase.
 3. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
-4. **Requirements analysis.** If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors.
+4. **Requirements analysis.** If `.gsd/REQUIREMENTS.md` exists, research against it and treat Active requirements as the capability contract for this milestone. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage in the roadmap.
 
 ### Strategic Questions to Answer
 
@@ -47,7 +53,7 @@ Then:
 2. {{skillActivation}}
 3. Create the roadmap: decompose into demoable vertical slices — as many as the work genuinely needs, no more. A simple feature might be 1 slice. Don't decompose for decomposition's sake.
 4. Order by risk (high-risk first)
-5. Call `gsd_plan_milestone` to persist the milestone planning fields, slice rows, and **horizontal checklist** in the DB-backed planning path. Do **not** write `{{outputPath}}`, `ROADMAP.md`, or other planning artifacts manually — the planning tool owns roadmap rendering and persistence.
+5. Call `gsd_plan_milestone` to persist the milestone planning fields, slice rows, and **horizontal checklist** in the DB-backed planning path. Fill the Horizontal Checklist with cross-cutting concerns considered during planning (requirements re-read, decisions re-evaluated, graceful shutdown, revenue paths, auth boundary, shared resources, reconnection). Omit it for trivial milestones where none apply. Do **not** write `{{outputPath}}`, `ROADMAP.md`, or other planning artifacts manually — the planning tool owns roadmap rendering and persistence.
 6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), call `gsd_decision_save` for each decision — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 ## Requirement Mapping Rules

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
+- The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **scout** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.
@@ -56,7 +66,7 @@ Narrate your decomposition reasoning — why you're grouping work this way, what
 {{executorContextConstraints}}
 
 Then:
-0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
+0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. Owned requirements are acceptance criteria for this slice — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met. Supporting requirements are compatibility constraints only; do not pull a later slice's primary work into this slice unless the roadmap explicitly assigns that work here.
 0a. Call `memory_query` with keywords from the slice title and the source files listed below. Prior architectural decisions, conventions, and gotchas in this area should inform task decomposition — not be re-derived during execution.
 1. Read the templates:
    - `~/.gsd/agent/extensions/gsd/templates/plan.md`
@@ -70,7 +80,7 @@ Then:
    - Planned test files must only read from or import paths that are tracked in git. Do NOT plan tests whose inputs or fixtures are paths listed in `.gitignore` (e.g. `.gsd/`, `.planning/`, `.audits/`). If the scenario seems to require such a file, plan an inline fixture or a tracked sample instead.
 4. **For non-trivial slices only** — plan observability, proof level, and integration closure:
    - Include `Observability / Diagnostics` for backend, integration, async, stateful, or UI slices where failure diagnosis matters.
-   - Fill `Proof Level` and `Integration Closure` when the slice crosses runtime boundaries or has meaningful integration concerns.
+   - Fill `Proof Level` and `Integration Closure` truthfully when the slice crosses runtime boundaries or has meaningful integration concerns — say what class of proof this slice really delivers and what end-to-end wiring still remains. Do not phrase fixture/contract-only proof as if it were live integration proof.
    - **Omit these sections entirely for simple slices** where they would all be "none" or trivially obvious.
 5. **Quality gates** — for non-trivial slices, fill the Threat Surface (Q3) and Requirement Impact (Q4) sections in the slice plan:
    - **Threat Surface:** Identify abuse scenarios, data exposure risks, and input trust boundaries. Required when the slice handles user input, authentication, authorization, or sensitive data. Omit entirely for internal refactoring or simple changes.
@@ -82,16 +92,18 @@ Then:
    - a matching task plan file with description, steps, must-haves, verification, inputs, and expected output
    - **Inputs and Expected Output must list concrete backtick-wrapped file paths** (e.g. `` `src/types.ts` ``). These are machine-parsed to derive task dependencies — vague prose without paths breaks parallel execution. Every task must have at least one output file path.
    - Observability Impact section **only if the task touches runtime boundaries, async flows, or error paths** — omit it otherwise
-7. **Persist planning state through `gsd_plan_slice`.** Call it with the full slice planning payload (goal, demo, must-haves, verification, tasks, and metadata). The tool inserts all tasks in the same transaction, writes to the DB, and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** call `gsd_plan_task` separately — `gsd_plan_slice` handles task persistence. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tool is the canonical write path for slice and task planning state.
+7. **Persist planning state through `gsd_plan_slice`.** Call it with the full slice planning payload: `goal`, `successCriteria`, optional `proofLevel`, optional `integrationClosure`, optional `observabilityImpact`, and `tasks`. Keep each task description's first paragraph concise; detailed steps and must-haves may follow, but the parent slice plan should read as a summary. The tool inserts all tasks in the same transaction, writes to the DB, and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** call `gsd_plan_task` separately — `gsd_plan_slice` handles task persistence. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tool is the canonical write path for slice and task planning state.
 8. **Self-audit the plan.** Walk through each check — if any fail, fix the plan files before moving on:
     - **Completion semantics:** If every task were completed exactly as written, the slice goal/demo should actually be true.
-    - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task.
+    - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task with verification that proves the requirement is met.
+    - **Decisions honored:** The plan respects locked decisions from any inlined context, research, or `.gsd/DECISIONS.md` artifacts. Do not silently re-litigate prior decisions.
     - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague. Inputs and Expected Output list backtick-wrapped file paths, not prose descriptions.
     - **Dependency correctness:** Task ordering is consistent. No task references work from a later task.
     - **Key links planned:** For every pair of artifacts that must connect, there is an explicit step that wires them.
     - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.
-    - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding.
-    - **Quality gate coverage:** For non-trivial slices, Threat Surface and Requirement Impact sections are present and specific (not placeholder text). For non-trivial tasks, Failure Modes, Load Profile, and Negative Tests are addressed in the task plan.
+    - **Proof-level truthfulness:** The proof-level wording does not overclaim live integration if only fixture/contract proof is planned.
+    - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding. If the slice has a UI surface, at least one task builds the real UI; if it has an API, at least one task connects it to a real data source. Showing the completed result to a non-technical stakeholder should demonstrate real product progress rather than developer artifacts.
+    - **Quality gate coverage:** For non-trivial slices, Threat Surface (Q3: abuse, data exposure, input trust) and Requirement Impact (Q4: requirements touched, re-verify, decisions revisited) sections are present and specific (not placeholder text). For non-trivial tasks, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) are addressed in the task plan.
 10. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
 11. {{commitInstruction}}
 

package/dist/resources/extensions/gsd/prompts/refine-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
+### Delegate Recon When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate recon and sub-decomposition. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem touched by the sketch → dispatch the **scout** agent and work from its compressed report.
+- A specific area of the refinement needs deeper architectural analysis → dispatch the **planner** agent for a focused sub-plan, then integrate.
+- You need current external information (library docs, API behavior) → dispatch the **scout** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) — they would write user source and bypass write isolation. Implementation belongs in `execute-task`.
+
 ### Respect the Sketch Scope
 
 The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.

package/dist/resources/extensions/gsd/prompts/rewrite-docs.md

@@ -1,5 +1,7 @@
 You are executing GSD auto-mode.
 
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
 ## UNIT: Rewrite Documents — Apply Override(s) for Milestone {{milestoneId}} ("{{milestoneTitle}}")
 
 An override was issued by the user that changes a fundamental decision or approach. Your job is to propagate this change across all active planning documents so they are internally consistent and future tasks execute correctly.

package/dist/resources/extensions/gsd/prompts/system.md

@@ -35,7 +35,7 @@ GSD ships with bundled skills. Load the relevant skill file with the `read` tool
 - Read before edit.
 - Reproduce before fix when possible.
 - Work is not done until the relevant verification has passed.
-- **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar to represent user input inside your own output. Prior conversation context may be provided to you inside `<conversation_history>` with `<user_message>` / `<assistant_message>` XML tags — treat those as read-only context and never emit those tags in your response. Ask one question round (1-3 questions), then stop and wait for the user's actual response before continuing. If `ask_user_questions` is available, treat its returned response as the only valid structured user input for that round.
+- **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar to represent user input inside your own output. Prior conversation context may be provided to you inside `<conversation_history>` with `<user_message>` / `<assistant_message>` XML tags — treat those as read-only context and never emit those tags in your response. Ask one question round (1-3 questions), then stop and wait for the user's actual response before continuing. If `ask_user_questions` is available, treat its returned response as the only valid structured user input for that round. If `ask_user_questions` is cancelled, fails, or returns no response, never treat earlier chat as confirmation for the current gate; ask in plain chat and stop.
 - Never print, echo, log, or restate secrets or credentials. Report only key names and applied/skipped status.
 - Never ask the user to edit `.env` files or set secrets manually. Use `secure_env_collect`.
 - In enduring files, write current state only unless the file is explicitly historical.
@@ -90,11 +90,11 @@ Titles live inside file content (headings, frontmatter), not in file or director
 
 ### Isolation Model
 
-Auto-mode supports three isolation modes (configured in `.gsd/PREFERENCES.md` under `taskIsolation.mode`):
+Auto-mode supports three isolation modes (configured in `.gsd/PREFERENCES.md` under `git.isolation`):
 
-- **worktree** (default): Work happens in `.gsd/worktrees/<MID>/`, a full git worktree on the `milestone/<MID>` branch. Each worktree has its own working copy and `.gsd/` directory. Squash-merged back to the integration branch on milestone completion.
+- **none** (default): Work happens directly on the current branch. No worktree, no milestone branch. Commits land in-place.
+- **worktree**: Work happens in `.gsd/worktrees/<MID>/`, a full git worktree on the `milestone/<MID>` branch. Each worktree has its own working copy and `.gsd/` directory. Squash-merged back to the integration branch on milestone completion.
 - **branch**: Work happens in the project root on a `milestone/<MID>` branch. No worktree directory — files are checked out in-place.
-- **none**: Work happens directly on the current branch. No worktree, no milestone branch. Commits land in-place.
 
 In all modes, slices commit sequentially on the active branch; there are no per-slice branches.
 

package/dist/resources/extensions/gsd/queue-order.js

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
 import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { isDbAvailable, setMilestoneQueueOrder } from "./gsd-db.js";
 // ─── Path ────────────────────────────────────────────────────────────────────
 function queueOrderPath(basePath) {
     return join(gsdRoot(basePath), "QUEUE-ORDER.json");
@@ -30,9 +31,13 @@ export function loadQueueOrder(basePath) {
     return data?.order ?? null;
 }
 /**
- * Save a custom queue order to disk.
+ * Save a custom queue order. The DB sequence is canonical when a DB
+ * connection is open; QUEUE-ORDER.json remains a compatibility projection.
  */
 export function saveQueueOrder(basePath, order) {
+    if (isDbAvailable()) {
+        setMilestoneQueueOrder(order);
+    }
     const data = {
         order,
         updatedAt: new Date().toISOString(),

package/dist/resources/extensions/gsd/repo-identity.js

@@ -8,9 +8,8 @@
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "./gsd-home.js";
 function isRepoMeta(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -152,7 +151,7 @@ function isProjectGsd(gsdPath) {
         // Recompute gsdHome dynamically so env overrides (GSD_HOME) are
         // picked up at call time, not just at module load time.
         if (stat.isDirectory()) {
-            const currentGsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+            const currentGsdHome = gsdHome();
             const normalizedGsdPath = canonicalizeExistingPath(gsdPath);
             const normalizedGsdHome = canonicalizeExistingPath(currentGsdHome);
             if (normalizedGsdPath === normalizedGsdHome)
@@ -288,7 +287,7 @@ export function repoIdentity(basePath) {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath) {
-    const base = process.env.GSD_STATE_DIR || gsdHome;
+    const base = process.env.GSD_STATE_DIR || gsdHome();
     return join(base, "projects", repoIdentity(basePath));
 }
 /**
@@ -296,7 +295,7 @@ export function externalGsdRoot(basePath) {
  * Honors GSD_STATE_DIR override before falling back to GSD_HOME.
  */
 export function externalProjectsRoot() {
-    const base = process.env.GSD_STATE_DIR || gsdHome;
+    const base = process.env.GSD_STATE_DIR || gsdHome();
     return join(base, "projects");
 }
 // ─── Numbered Variant Cleanup ────────────────────────────────────────────────
@@ -416,7 +415,7 @@ function resolveExternalPathWithRecovery(projectPath) {
     const markerId = readGsdIdMarker(projectPath);
     if (markerId && markerId !== computedId) {
         // The marker points to a different identity — the repo was likely moved.
-        const base = process.env.GSD_STATE_DIR || gsdHome;
+        const base = process.env.GSD_STATE_DIR || gsdHome();
         const markerPath = join(base, "projects", markerId);
         if (hasProjectState(markerPath)) {
             // Recover: use the old state directory and update the marker to the new identity.
@@ -484,9 +483,21 @@ function ensureGsdSymlinkCore(projectPath) {
     // Guard: Never create a symlink at ~/.gsd — that's the user-level GSD home,
     // not a project .gsd. This can happen if resolveProjectRoot() or
     // escapeStaleWorktree() returned ~ as the project root (#1676).
-    const localGsdNormalized = localGsd.replaceAll("\\", "/");
-    const gsdHomePath = gsdHome.replaceAll("\\", "/");
-    if (localGsdNormalized === gsdHomePath) {
+    // Canonical normalization: resolve symlinks, trim trailing slashes, case-fold on Windows.
+    const normalizeForGuard = (p) => {
+        let resolved;
+        try {
+            resolved = realpathSync(p);
+        }
+        catch {
+            resolved = resolve(p);
+        }
+        const s = resolved.replaceAll("\\", "/").replace(/\/+$/, "");
+        return process.platform === "win32" ? s.toLowerCase() : s;
+    };
+    const localGsdNormalized = normalizeForGuard(localGsd);
+    const gsdHomeNorm = normalizeForGuard(gsdHome());
+    if (localGsdNormalized === gsdHomeNorm) {
         return localGsd;
     }
     // Guard: If projectPath is a plain subdirectory (not a worktree) of a git

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

@@ -17,13 +17,14 @@ import { getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
 import { buildExistingMilestonesContext } from "./guided-flow-queue.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { isGsdGitignored } from "./gitignore.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 export async function handleRethink(_args, ctx, pi) {
     if (isAutoActive()) {
         ctx.ui.notify("Cannot rethink while auto-mode is active. Stop auto-mode first.", "error");
         return;
     }
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const root = gsdRoot(basePath);
     if (!existsSync(root)) {
         ctx.ui.notify("No GSD project found. Run /gsd init first.", "warning");

package/dist/resources/extensions/gsd/safety/git-checkpoint.js

@@ -18,7 +18,7 @@ const CHECKPOINT_PREFIX = "refs/gsd/checkpoints/";
  */
 export function createCheckpoint(basePath, unitId) {
     try {
-        const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+        const sha = execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
             cwd: basePath,
             stdio: ["ignore", "pipe", "pipe"],
             encoding: "utf-8",
@@ -34,6 +34,13 @@ export function createCheckpoint(basePath, unitId) {
         return sha;
     }
     catch (e) {
+        const stderr = e.stderr;
+        const stderrText = Buffer.isBuffer(stderr) ? stderr.toString("utf-8") : String(stderr ?? "");
+        if (stderrText.includes("Needed a single revision") ||
+            stderrText.includes("unknown revision") ||
+            stderrText.includes("ambiguous argument 'HEAD'")) {
+            return null;
+        }
         logWarning("safety", `checkpoint creation failed: ${e.message}`);
         return null;
     }

package/dist/resources/extensions/gsd/schemas/__fixtures__/valid-project.md

@@ -0,0 +1,26 @@
+# Project
+
+## What This Is
+
+A test project for validating Phase 11 deep planning mode artifact contracts.
+
+## Core Value
+
+The project must produce reliable validation results for malformed artifacts.
+
+## Current State
+
+Phase 11 dispatch units are landed. Validators are being built.
+
+## Architecture / Key Patterns
+
+TypeScript monorepo with markdown artifacts, AJV-style validators, parser-then-schema pattern.
+
+## Capability Contract
+
+See `.gsd/REQUIREMENTS.md` for the explicit capability contract.
+
+## Milestone Sequence
+
+- [ ] M001: Validators — build the runtime artifact validation framework
+- [ ] M002: Manifest — extend DISCUSSION-MANIFEST.json with planning stages

package/dist/resources/extensions/gsd/schemas/__fixtures__/valid-requirements.md

@@ -0,0 +1,57 @@
+# Requirements
+
+## Active
+
+### R001 — Validators reject malformed artifacts
+- Class: core-capability
+- Status: active
+- Description: validateArtifact returns ok=false when required sections are missing
+- Why it matters: prevents malformed PROJECT.md/REQUIREMENTS.md from propagating to downstream stages
+- Source: spec
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: unmapped
+- Notes: contract spec at 11-CONTRACTS.md
+
+## Validated
+
+## Deferred
+
+### R020 — Schema versioning
+- Class: operability
+- Status: deferred
+- Description: schema_version field in DISCUSSION-MANIFEST.json
+- Why it matters: enables backward-compat migrations
+- Source: research
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: unmapped
+- Notes: lands with manifest extension in M002
+
+## Out of Scope
+
+### R030 — Real-time validation
+- Class: anti-feature
+- Status: out-of-scope
+- Description: file watcher that validates on every save
+- Why it matters: prevents scope creep into IDE tooling
+- Source: inferred
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: out of scope for Phase 11
+
+## Traceability
+
+| ID | Class | Status | Primary owner | Supporting | Proof |
+|---|---|---|---|---|---|
+| R001 | core-capability | active | M001/S01 | none | unmapped |
+| R020 | operability | deferred | none | none | unmapped |
+| R030 | anti-feature | out-of-scope | none | none | n/a |
+
+## Coverage Summary
+
+- Active requirements: 1
+- Mapped to slices: 1
+- Validated: 0
+- Unmapped active requirements: 0

package/dist/resources/extensions/gsd/schemas/__fixtures__/valid-roadmap.md

@@ -0,0 +1,19 @@
+# M001 Roadmap
+
+## Slices
+
+### S01 — Validator framework
+- Risk: low
+- Depends: none
+- Demo: validateArtifact() returns structured ValidationResult for fixture files
+
+### S02 — Cross-reference checks
+- Risk: medium
+- Depends: S01
+- Demo: requirements with dangling milestone references are flagged
+
+## Definition of Done
+
+- All three validators (project, requirements, roadmap) live behind validateArtifact()
+- 90%+ test coverage on the validator module
+- Deep-mode dispatch rules call validateArtifact before stage gate clears