gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.1afbdaa

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

@@ -8,7 +8,7 @@ import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
-import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth } from "./doctor-checks.js";
+import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
 export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt, formatDoctorReportJson } from "./doctor-format.js";
@@ -332,8 +332,8 @@ export async function runGSDDoctor(basePath, options) {
     // Git health checks — timed
     const t0git = Date.now();
     const isolationMode = options?.isolationMode ??
-        (prefs?.preferences?.git?.isolation === "none" ? "none" :
-            prefs?.preferences?.git?.isolation === "branch" ? "branch" : "worktree");
+        (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
+            prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
     await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
     const gitMs = Date.now() - t0git;
     // Runtime health checks — timed
@@ -350,6 +350,8 @@ export async function runGSDDoctor(basePath, options) {
         includeTests: options?.includeTests,
     });
     const envMs = Date.now() - t0env;
+    // Engine health checks — DB constraints and projection drift
+    await checkEngineHealth(basePath, issues, fixesApplied);
     const milestonesPath = milestonesDir(basePath);
     if (!existsSync(milestonesPath)) {
         const report = { ok: issues.every(i => i.severity !== "error"), basePath, issues, fixesApplied, timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: 0 } };
@@ -441,6 +443,7 @@ export async function runGSDDoctor(basePath, options) {
                 id: s.id,
                 title: s.title,
                 done: s.status === "complete",
+                pending: s.status === "pending",
                 risk: (s.risk || "medium"),
                 depends: s.depends,
                 demo: s.demo,
@@ -528,6 +531,10 @@ export async function runGSDDoctor(basePath, options) {
             }
             const slicePath = resolveSlicePath(basePath, milestoneId, slice.id);
             if (!slicePath) {
+                // Pending slices haven't been planned yet — directories are created
+                // lazily by ensurePreconditions() at dispatch time. Skip them.
+                if (slice.pending)
+                    continue;
                 const expectedPath = relSlicePath(basePath, milestoneId, slice.id);
                 issues.push({
                     severity: slice.done ? "warning" : "error",
@@ -549,6 +556,9 @@ export async function runGSDDoctor(basePath, options) {
             }
             const tasksDir = resolveTasksDir(basePath, milestoneId, slice.id);
             if (!tasksDir) {
+                // Pending slices haven't been planned yet — tasks/ is created on demand.
+                if (slice.pending)
+                    continue;
                 issues.push({
                     severity: slice.done ? "warning" : "error",
                     code: "missing_tasks_dir",

package/dist/resources/extensions/gsd/git-service.js

@@ -510,13 +510,18 @@ export class GitServiceImpl {
  * Returns the PR URL on success, or null on failure.
  * Non-fatal: callers should treat failure as best-effort.
  */
-export function createDraftPR(basePath, milestoneId, title, body) {
+export function createDraftPR(basePath, milestoneId, title, body, opts) {
     try {
-        const result = execFileSync("gh", [
+        const args = [
             "pr", "create", "--draft",
             "--title", title,
             "--body", body,
-        ], { cwd: basePath, encoding: "utf8", timeout: 30000, env: GIT_NO_PROMPT_ENV });
+        ];
+        if (opts?.head)
+            args.push("--head", opts.head);
+        if (opts?.base)
+            args.push("--base", opts.base);
+        const result = execFileSync("gh", args, { cwd: basePath, encoding: "utf8", timeout: 30000, env: GIT_NO_PROMPT_ENV });
         return result.trim();
     }
     catch {

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

@@ -56,7 +56,11 @@ function loadProvider() {
     catch {
         // unavailable
     }
-    process.stderr.write("gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3)\n");
+    const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+    const versionHint = nodeMajor < 22
+        ? ` GSD requires Node >= 22.0.0 (current: v${process.versions.node}). Upgrade Node to fix this.`
+        : "";
+    process.stderr.write(`gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3).${versionHint}\n`);
 }
 function normalizeRow(row) {
     if (row == null)
@@ -105,7 +109,7 @@ function openRawDb(path) {
     const Database = providerModule;
     return new Database(path);
 }
-const SCHEMA_VERSION = 10;
+const SCHEMA_VERSION = 11;
 function initSchema(db, fileBacked) {
     if (fileBacked)
         db.exec("PRAGMA journal_mode=WAL");
@@ -253,6 +257,7 @@ function initSchema(db, fileBacked) {
         inputs TEXT NOT NULL DEFAULT '[]',
         expected_output TEXT NOT NULL DEFAULT '[]',
         observability_impact TEXT NOT NULL DEFAULT '',
+        full_plan_md TEXT NOT NULL DEFAULT '',
         sequence INTEGER DEFAULT 0, -- DEAD CODE: no tool exposes sequence — always 0
         PRIMARY KEY (milestone_id, slice_id, id),
         FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
@@ -542,6 +547,20 @@ function migrateSchema(db) {
                 ":applied_at": new Date().toISOString(),
             });
         }
+        if (currentVersion < 11) {
+            ensureColumn(db, "tasks", "full_plan_md", `ALTER TABLE tasks ADD COLUMN full_plan_md TEXT NOT NULL DEFAULT ''`);
+            // Add unique constraint to replan_history for idempotency:
+            // one replan record per blocker task per slice per milestone.
+            db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_replan_history_unique
+        ON replan_history(milestone_id, slice_id, task_id)
+        WHERE slice_id IS NOT NULL AND task_id IS NOT NULL
+      `);
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+                ":version": 11,
+                ":applied_at": new Date().toISOString(),
+            });
+        }
         db.exec("COMMIT");
     }
     catch (err) {
@@ -997,7 +1016,8 @@ export function upsertTaskPlanning(milestoneId, sliceId, taskId, planning) {
       verify = COALESCE(:verify, verify),
       inputs = COALESCE(:inputs, inputs),
       expected_output = COALESCE(:expected_output, expected_output),
-      observability_impact = COALESCE(:observability_impact, observability_impact)
+      observability_impact = COALESCE(:observability_impact, observability_impact),
+      full_plan_md = COALESCE(:full_plan_md, full_plan_md)
      WHERE milestone_id = :milestone_id AND slice_id = :slice_id AND id = :id`).run({
         ":milestone_id": milestoneId,
         ":slice_id": sliceId,
@@ -1010,6 +1030,7 @@ export function upsertTaskPlanning(milestoneId, sliceId, taskId, planning) {
         ":inputs": planning.inputs ? JSON.stringify(planning.inputs) : null,
         ":expected_output": planning.expectedOutput ? JSON.stringify(planning.expectedOutput) : null,
         ":observability_impact": planning.observabilityImpact ?? null,
+        ":full_plan_md": planning.fullPlanMd ?? null,
     });
 }
 function rowToSlice(row) {
@@ -1078,6 +1099,7 @@ function rowToTask(row) {
         inputs: JSON.parse(row["inputs"] || "[]"),
         expected_output: JSON.parse(row["expected_output"] || "[]"),
         observability_impact: row["observability_impact"] ?? "",
+        full_plan_md: row["full_plan_md"] ?? "",
         sequence: row["sequence"] ?? 0,
     };
 }
@@ -1300,7 +1322,9 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
 export function insertReplanHistory(entry) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare(`INSERT INTO replan_history (milestone_id, slice_id, task_id, summary, previous_artifact_path, replacement_artifact_path, created_at)
+    // INSERT OR REPLACE: idempotent on (milestone_id, slice_id, task_id) via schema v11 unique index.
+    // Retrying the same replan silently updates summary instead of accumulating duplicate rows.
+    currentDb.prepare(`INSERT OR REPLACE INTO replan_history (milestone_id, slice_id, task_id, summary, previous_artifact_path, replacement_artifact_path, created_at)
      VALUES (:milestone_id, :slice_id, :task_id, :summary, :previous_artifact_path, :replacement_artifact_path, :created_at)`).run({
         ":milestone_id": entry.milestoneId,
         ":slice_id": entry.sliceId ?? null,

package/dist/resources/extensions/gsd/guided-flow.js

@@ -755,8 +755,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // when the user exits during init wizard or discuss phase before any
         // real auto-mode work begins.
         const isBootstrapCrash = crashLock.unitType === "starting"
-            && crashLock.unitId === "bootstrap"
-            && crashLock.completedUnits === 0;
+            && crashLock.unitId === "bootstrap";
         if (!isBootstrapCrash) {
             const resume = await showNextAction(ctx, {
                 title: "GSD — Interrupted Session Detected",

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -298,7 +298,7 @@ export async function renderTaskPlanFromDb(basePath, milestoneId, sliceId, taskI
     mkdirSync(tasksDir, { recursive: true });
     const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
     const artifactPath = toArtifactPath(absPath, basePath);
-    const content = renderTaskPlanMarkdown(task);
+    const content = task.full_plan_md.trim() ? task.full_plan_md : renderTaskPlanMarkdown(task);
     await writeAndStore(absPath, artifactPath, content, {
         artifact_type: "PLAN",
         milestone_id: milestoneId,

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -17,7 +17,7 @@ import { getErrorMessage } from "./error-utils.js";
  * By-completion: merge in the order milestones finished.
  */
 export function determineMergeOrder(workers, order = "sequential") {
-    const completed = workers.filter(w => w.state === "stopped" && w.completedUnits > 0);
+    const completed = workers.filter(w => w.state === "stopped");
     if (order === "by-completion") {
         return completed
             .sort((a, b) => a.startedAt - b.startedAt) // earliest first

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -47,7 +47,6 @@ export function persistState(basePath) {
                 worktreePath: w.worktreePath,
                 startedAt: w.startedAt,
                 state: w.state,
-                completedUnits: w.completedUnits,
                 cost: w.cost,
             })),
             totalCost: state.totalCost,
@@ -158,7 +157,6 @@ function restoreRuntimeState(basePath) {
                 worktreePath: diskStatus?.worktreePath ?? w.worktreePath,
                 startedAt: w.startedAt,
                 state: diskStatus?.state ?? w.state,
-                completedUnits: diskStatus?.completedUnits ?? w.completedUnits,
                 cost: diskStatus?.cost ?? w.cost,
             });
         }
@@ -189,7 +187,6 @@ function restoreRuntimeState(basePath) {
             worktreePath: status.worktreePath,
             startedAt: status.startedAt,
             state: status.state,
-            completedUnits: status.completedUnits,
             cost: status.cost,
         });
         state.totalCost += status.cost;
@@ -296,7 +293,6 @@ export async function startParallel(basePath, milestoneIds, prefs) {
                 worktreePath: w.worktreePath,
                 startedAt: w.startedAt,
                 state: "running",
-                completedUnits: w.completedUnits,
                 cost: w.cost,
             });
             adopted.push(w.milestoneId);
@@ -341,7 +337,6 @@ export async function startParallel(basePath, milestoneIds, prefs) {
                 worktreePath: wtPath,
                 startedAt: now,
                 state: "running",
-                completedUnits: 0,
                 cost: 0,
             };
             state.workers.set(mid, worker);
@@ -486,7 +481,7 @@ export function spawnWorker(basePath, milestoneId) {
         pid: worker.pid,
         state: "running",
         currentUnit: null,
-        completedUnits: worker.completedUnits,
+        completedUnits: 0,
         cost: worker.cost,
         lastHeartbeat: Date.now(),
         startedAt: worker.startedAt,
@@ -527,7 +522,7 @@ export function spawnWorker(basePath, milestoneId) {
             pid: w.pid,
             state: w.state,
             currentUnit: null,
-            completedUnits: w.completedUnits,
+            completedUnits: 0,
             cost: w.cost,
             lastHeartbeat: Date.now(),
             startedAt: w.startedAt,
@@ -602,13 +597,6 @@ function processWorkerLine(basePath, milestoneId, line) {
                 }
             }
         }
-        // Track completed units (each message_end from assistant = progress)
-        if (msg.role === "assistant") {
-            const worker = state.workers.get(milestoneId);
-            if (worker) {
-                worker.completedUnits++;
-            }
-        }
         // Update session status file so dashboard sees live cost
         const worker = state.workers.get(milestoneId);
         if (worker) {
@@ -617,7 +605,7 @@ function processWorkerLine(basePath, milestoneId, line) {
                 pid: worker.pid,
                 state: worker.state,
                 currentUnit: null,
-                completedUnits: worker.completedUnits,
+                completedUnits: 0,
                 cost: worker.cost,
                 lastHeartbeat: Date.now(),
                 startedAt: worker.startedAt,
@@ -635,7 +623,7 @@ function processWorkerLine(basePath, milestoneId, line) {
                 pid: worker.pid,
                 state: worker.state,
                 currentUnit: null,
-                completedUnits: worker.completedUnits,
+                completedUnits: 0,
                 cost: worker.cost,
                 lastHeartbeat: Date.now(),
                 startedAt: worker.startedAt,
@@ -776,13 +764,12 @@ export function refreshWorkerStatuses(basePath, options = {}) {
             if (!isPidAlive(worker.pid)) {
                 worker.cleanup?.();
                 worker.cleanup = undefined;
-                worker.state = worker.completedUnits > 0 ? "stopped" : "error";
+                worker.state = "error";
                 worker.process = null;
             }
             continue;
         }
         worker.state = diskStatus.state;
-        worker.completedUnits = diskStatus.completedUnits;
         worker.cost = diskStatus.cost;
         worker.pid = diskStatus.pid;
     }

package/dist/resources/extensions/gsd/preferences-types.js

@@ -13,7 +13,7 @@ export const MODE_DEFAULTS = {
             push_branches: false,
             pre_merge_check: false,
             merge_strategy: "squash",
-            isolation: "worktree",
+            isolation: "none",
         },
         unique_milestone_ids: false,
     },
@@ -23,7 +23,7 @@ export const MODE_DEFAULTS = {
             push_branches: true,
             pre_merge_check: true,
             merge_strategy: "squash",
-            isolation: "worktree",
+            isolation: "none",
         },
         unique_milestone_ids: true,
     },

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

@@ -393,15 +393,19 @@ export function resolvePreDispatchHooks() {
 // ─── Isolation & Parallel ─────────────────────────────────────────────────────
 /**
  * Resolve the effective git isolation mode from preferences.
- * Returns "worktree" (default), "branch", or "none".
+ * Returns "none" (default), "worktree", or "branch".
+ *
+ * Default is "none" so GSD works out of the box without preferences.md.
+ * Worktree isolation requires explicit opt-in because it depends on git
+ * branch infrastructure that must be set up before use.
  */
 export function getIsolationMode() {
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    if (prefs?.isolation === "none")
-        return "none";
+    if (prefs?.isolation === "worktree")
+        return "worktree";
     if (prefs?.isolation === "branch")
         return "branch";
-    return "worktree"; // default
+    return "none"; // default — no isolation, work on current branch
 }
 export function resolveParallelConfig(prefs) {
     return {

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

@@ -17,20 +17,31 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 Then:
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. In that case, do NOT mark the milestone as passing verification — document the gap clearly in the summary and state that implementation is missing.
-4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
-5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
+3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. Record this as a **verification failure**.
+4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. Record any criterion that was NOT met as a **verification failure**.
+5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly. Record any unmet items as a **verification failure**.
 6. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
-7. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
-8. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
+
+### Verification Gate — STOP if verification failed
+
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 7.**
+
+**Failure path** (verification failed):
+- Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
+- Do NOT update `.gsd/PROJECT.md` to reflect completion.
+- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements as validated.
+- Write a clear summary of what failed and why to help the next attempt.
+- Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
+
+**Success path** (all verifications passed — continue with steps 7–11):
+
+7. **Persist completion through `gsd_complete_milestone`.** Call it with: `milestoneId`, `title`, `oneLiner`, `narrative`, `successCriteriaResults`, `definitionOfDoneResults`, `requirementOutcomes`, `keyDecisions`, `keyFiles`, `lessonsLearned`, `followUps`, `deviations`, `verificationPassed: true`. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
+8. For each requirement whose status changed in step 6, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
 9. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
 10. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
 11. Do not commit manually — the system auto-commits your changes after this unit completes.
+- Say: "Milestone {{milestoneId}} complete."
 
-**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met or no code changes exist, document it clearly in the summary and do not mark the milestone as passing verification.
+**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run.
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
-
-**You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
-
-When done, say: "Milestone {{milestoneId}} complete."

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

@@ -23,28 +23,15 @@ Then:
 2. {{skillActivation}}
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
-6. Call the `gsd_slice_complete` tool (alias: `gsd_complete_slice`) to record the slice as complete. The tool validates all tasks are complete, updates the slice status in the DB, renders the summary to `{{sliceSummaryPath}}`, UAT to `{{sliceUatPath}}`, and re-renders `{{roadmapPath}}` — all atomically. Read the summary and UAT templates at `~/.gsd/agent/extensions/gsd/templates/` to understand the expected structure, then pass the following parameters:
-
-   **Identity:** `sliceId`, `milestoneId`, `sliceTitle`
-
-   **Narrative:** `oneLiner` (one-line summary of what the slice accomplished), `narrative` (detailed account of what happened across all tasks), `verification` (what was verified and how), `deviations` (deviations from plan, or "None."), `knownLimitations` (gaps or limitations, or "None."), `followUps` (follow-up work discovered, or "None.")
-
-   **Files:** `keyFiles` (array of key file paths), `filesModified` (array of `{path, description}` objects for all files changed)
-
-   **Requirements:** `requirementsAdvanced` (array of `{id, how}`), `requirementsValidated` (array of `{id, proof}`), `requirementsInvalidated` (array of `{id, what}`), `requirementsSurfaced` (array of new requirement strings)
-
-   **Patterns & decisions:** `keyDecisions` (array of decision strings), `patternsEstablished` (array), `observabilitySurfaces` (array)
-
-   **Dependencies:** `provides` (what this slice provides downstream), `affects` (downstream slice IDs affected), `requires` (array of `{slice, provides}` for upstream dependencies consumed), `drillDownPaths` (paths to task summaries)
-
-   **UAT content:** `uatContent` — the UAT markdown body. This must be a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built. The tool writes it to `{{sliceUatPath}}`.
-
-7. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-8. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
-9. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-10. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
-
-**You MUST call `gsd_slice_complete` before finishing.** The tool handles writing `{{sliceSummaryPath}}`, `{{sliceUatPath}}`, and updating `{{roadmapPath}}` atomically. You must still review decisions and knowledge manually (steps 7-8).
+5. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
+6. Write `{{sliceSummaryPath}}` (compress all task summaries).
+7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
+8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
+9. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+10. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
+11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
+12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
+
+**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) call `gsd_complete_slice`. The unit will not be marked complete if any of these are missing.**
 
 When done, say: "Slice {{sliceId}} complete."

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

@@ -203,7 +203,7 @@ When writing context.md, preserve the user's exact terminology, emphasis, and sp
 
 4. Write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
 5. Call `gsd_plan_milestone` to create the roadmap. Decompose into demoable vertical slices with risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. Use the **Roadmap** output template below to structure the tool call parameters.
-6. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below. Append rows for any architectural or pattern decisions made during discussion.
+6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
@@ -217,7 +217,7 @@ Once the user confirms the milestone split:
 1. For each milestone, call `gsd_milestone_generate_id` to get its ID — never invent milestone IDs manually. Then `mkdir -p .gsd/milestones/<ID>/slices`.
 2. Write `.gsd/PROJECT.md` — use the **Project** output template below.
 3. Write `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
-4. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below.
+4. For any architectural or pattern decisions made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 #### Phase 2: Primary milestone
 

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -63,23 +63,13 @@ Then:
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
 12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
 13. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
-14. Call the `gsd_task_complete` tool (alias: `gsd_complete_task`) to record the task completion. This single tool call atomically updates the task status in the DB, renders the summary file to `{{taskSummaryPath}}`, and re-renders the plan file at `{{planPath}}`. Read the summary template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md` to understand the expected structure — but pass the content as tool parameters, not as a file write. The tool parameters are:
-    - `taskId`: "{{taskId}}"
-    - `sliceId`: "{{sliceId}}"
-    - `milestoneId`: "{{milestoneId}}"
-    - `oneLiner`: One-line summary of what was accomplished (becomes the commit message)
-    - `narrative`: Detailed narrative of what happened during the task
-    - `verification`: What was verified and how — commands run, tests passed, behavior confirmed
-    - `deviations`: Deviations from the task plan, or "None."
-    - `knownIssues`: Known issues discovered but not fixed, or "None."
-    - `keyFiles`: Array of key files created or modified
-    - `keyDecisions`: Array of key decisions made during this task
-    - `blockerDiscovered`: Whether a plan-invalidating blocker was discovered (boolean)
-    - `verificationEvidence`: Array of `{ command, exitCode, verdict, durationMs }` objects from the verification gate
-15. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
+14. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
+15. Write `{{taskSummaryPath}}`
+16. Call `gsd_complete_task` with milestone_id, slice_id, task_id, and a summary of what was accomplished. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, and renders PLAN.md automatically.
+17. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
 
 All work stays in your working directory: `{{workingDirectory}}`.
 
-**You MUST call `gsd_task_complete` before finishing.** The tool handles writing `{{taskSummaryPath}}` and updating the plan file at `{{planPath}}` — do not write the summary file or modify the plan file manually.
+**You MUST call `gsd_complete_task` AND write `{{taskSummaryPath}}` before finishing.**
 
 When done, say: "Task {{taskId}} complete."

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -105,6 +105,6 @@ Once the user confirms depth:
 
 1. Use the **Context** output template below
 2. `mkdir -p` the milestone directory if needed
-3. Write `{{milestoneId}}-CONTEXT.md` — preserve the user's exact terminology, emphasis, and framing. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
+3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `artifact_type: "CONTEXT"`, and the full context markdown as `content` — the tool writes the file to disk and persists to DB. Preserve the user's exact terminology, emphasis, and framing in the content. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
 4. {{commitInstruction}}
 5. Say exactly: `"{{milestoneId}} context written."` — nothing else.

package/dist/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -48,7 +48,7 @@ Once the user is ready to wrap up:
 
 1. Use the **Slice Context** output template below
 2. `mkdir -p {{sliceDirPath}}`
-3. Write `{{contextPath}}` — use the template structure, filling in:
+3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT"`, and the context as `content` — the tool writes the file to disk and persists to DB. Use the template structure, filling in:
    - **Goal** — one sentence: what this slice delivers
    - **Why this Slice** — why now, what it unblocks
    - **Scope / In Scope** — what was confirmed in scope during the interview

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

@@ -1,3 +1,3 @@
-Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Use the **Slice Plan** and **Task Plan** output templates below. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.gsd/DECISIONS.md`. {{skillActivation}} Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — 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, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
+Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Use the **Slice Plan** and **Task Plan** output templates below. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Call `gsd_plan_slice` to persist the slice plan — the tool writes `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files to disk and persists to DB. Do **not** write plan files manually — use the DB-backed tool so state stays consistent. If planning produces structural decisions, call `gsd_decision_save` for each — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically. {{skillActivation}} Before finishing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — 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, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
 
 {{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/guided-research-slice.md

@@ -1,4 +1,4 @@
-Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. {{skillActivation}} Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs` — skip this for libraries already used in the codebase. Use the **Research** output template below. Write `{{sliceId}}-RESEARCH.md` in the slice directory.
+Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. {{skillActivation}} Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs` — skip this for libraries already used in the codebase. Use the **Research** output template below. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "RESEARCH"`, and the research content — the tool writes the file to disk and persists to DB.
 
 **You are the scout.** A planner agent reads your output in a fresh context to decompose this slice into tasks. Write for the planner — surface key files, where the work divides naturally, what to build first, and how to verify. If the research doc is vague, the planner re-explores code you already read. If it's precise, the planner decomposes immediately.
 

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

@@ -48,7 +48,7 @@ Then:
 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 and slice rows 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.
-6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined context above if the file doesn't exist yet)
+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

@@ -63,7 +63,7 @@ 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
-6. **Persist planning state through DB-backed tools.** Call `gsd_plan_slice` with the full slice planning payload (goal, demo, must-haves, verification, tasks, and metadata). Then call `gsd_plan_task` for each task to persist its planning fields. These tools write to the DB and render `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tools are the canonical write path for slice and task planning state.
+6. **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. **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.
@@ -72,9 +72,11 @@ Then:
     - **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.
-8. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
-9. {{commitInstruction}}
+10. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
+11. {{commitInstruction}}
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`.
 
+**You MUST write the file `{{outputPath}}` before finishing.**
+
 When done, say: "Slice {{sliceId}} planned."

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

@@ -8,7 +8,7 @@ Before asking "What do you want to add?", check the existing milestones context
 
 1. Tell the user which milestones have draft contexts and briefly summarize what each draft contains (read the draft file).
 2. Use `ask_user_questions` to ask per-draft milestone:
-   - **"Discuss now"** — Treat this draft as the primary topic. Read the draft content, use it as seed material, and conduct a focused discussion following the standard discussion flow (reflection → investigation → questioning → depth verification → requirements → roadmap). After the discussion, write the full CONTEXT.md and delete the `CONTEXT-DRAFT.md` file. The milestone is then ready for auto-planning.
+   - **"Discuss now"** — Treat this draft as the primary topic. Read the draft content, use it as seed material, and conduct a focused discussion following the standard discussion flow (reflection → investigation → questioning → depth verification → requirements → roadmap). After the discussion, call `gsd_summary_save` with the milestone ID and `artifact_type: "CONTEXT"` to write the full context — then delete the `CONTEXT-DRAFT.md` file. The milestone is then ready for auto-planning.
    - **"Leave for later"** — Keep the draft as-is. The user will discuss it in a future session. Auto-mode will continue to pause when it reaches this milestone.
 3. Handle all draft discussions before proceeding to new queue work.
 4. If no drafts exist in the context, skip this section entirely and proceed to "What do you want to add?"
@@ -108,7 +108,7 @@ The user confirms or corrects before you write. One depth verification per miles
 Once the user is satisfied, in a single pass for **each** new milestone:
 
 1. Call `gsd_milestone_generate_id` to get the milestone ID — never invent milestone IDs manually. Then `mkdir -p .gsd/milestones/<ID>/slices`.
-2. Write `.gsd/milestones/<ID>/<ID>-CONTEXT.md` — use the **Context** output template below. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution." **If this milestone depends on other milestones, add YAML frontmatter with `depends_on`:**
+2. Call `gsd_summary_save` with `milestone_id: <ID>`, `artifact_type: "CONTEXT"`, and the full context markdown as `content` — the tool computes the file path and persists to both DB and disk. Capture intent, scope, risks, constraints, integration points, and relevant requirements in the content. Mark the status as "Queued — pending auto-mode execution." **If this milestone depends on other milestones, include YAML frontmatter with `depends_on` in the content:**
    ```yaml
    ---
    depends_on: [M001, M002]

package/dist/resources/extensions/gsd/prompts/quick-task.md

@@ -21,7 +21,9 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
    - Use conventional commit messages (feat:, fix:, refactor:, etc.)
    - Stage only relevant files — never commit secrets or runtime files.
    - Commit logical units separately if the task involves distinct changes.
+   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.
 7. Write a brief summary to `{{summaryPath}}`:
+   - Quick tasks operate outside the milestone/slice/task DB structure, so `gsd_summary_save` (which requires a `milestone_id`) cannot be used here. Write the file directly.
 
 ```markdown
 # Quick Task: {{description}}