gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

package/src/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/src/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/src/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/src/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/src/resources/extensions/gsd/queue-order.ts

@@ -13,6 +13,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";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -63,9 +64,13 @@ export function loadQueueOrder(basePath: string): string[] | 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: string, order: string[]): void {
+  if (isDbAvailable()) {
+    setMilestoneQueueOrder(order);
+  }
   const data: QueueOrderFile = {
     order,
     updatedAt: new Date().toISOString(),

package/src/resources/extensions/gsd/repo-identity.ts

@@ -9,10 +9,9 @@
 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";
+import { gsdHome } from "./gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 // ─── Repo Metadata ───────────────────────────────────────────────────────────
 
@@ -168,7 +167,7 @@ function isProjectGsd(gsdPath: string): boolean {
     // 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) return false;
@@ -311,7 +310,7 @@ export function repoIdentity(basePath: string): string {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath: string): string {
-  const base = process.env.GSD_STATE_DIR || gsdHome;
+  const base = process.env.GSD_STATE_DIR || gsdHome();
   return join(base, "projects", repoIdentity(basePath));
 }
 
@@ -320,7 +319,7 @@ export function externalGsdRoot(basePath: string): string {
  * Honors GSD_STATE_DIR override before falling back to GSD_HOME.
  */
 export function externalProjectsRoot(): string {
-  const base = process.env.GSD_STATE_DIR || gsdHome;
+  const base = process.env.GSD_STATE_DIR || gsdHome();
   return join(base, "projects");
 }
 
@@ -441,7 +440,7 @@ function resolveExternalPathWithRecovery(projectPath: string): string {
   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.
@@ -510,9 +509,16 @@ function ensureGsdSymlinkCore(projectPath: string): string {
   // 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: string): string => {
+    let resolved: string;
+    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;
   }
 

package/src/resources/extensions/gsd/rethink.ts

@@ -20,6 +20,7 @@ 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 ──────────────────────────────────────────────────────────────
 
@@ -33,7 +34,7 @@ export async function handleRethink(
     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/src/resources/extensions/gsd/safety/git-checkpoint.ts

@@ -23,7 +23,7 @@ const CHECKPOINT_PREFIX = "refs/gsd/checkpoints/";
  */
 export function createCheckpoint(basePath: string, unitId: string): string | null {
   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",
@@ -41,6 +41,15 @@ export function createCheckpoint(basePath: string, unitId: string): string | nul
 
     return sha;
   } catch (e) {
+    const stderr = (e as { stderr?: Buffer | string }).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 as Error).message}`);
     return null;
   }

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