gsd-pi 2.43.0-next.7-dev.8fab558 → 2.43.0-next.7-dev.4684f0e

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { AuthStorage, DefaultResourceLoader, ModelRegistry, SettingsManager, SessionManager, createAgentSession, InteractiveMode, runPrintMode, runRpcMode, } from '@gsd/pi-coding-agent';
+import { AuthStorage, DefaultResourceLoader, ModelRegistry, runPackageCommand, SettingsManager, SessionManager, createAgentSession, InteractiveMode, runPrintMode, runRpcMode, } from '@gsd/pi-coding-agent';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentDir, sessionsDir, authFilePath } from './app-paths.js';
@@ -121,6 +121,18 @@ if (subcommand && process.argv.includes('--help')) {
         process.exit(0);
     }
 }
+const packageCommand = await runPackageCommand({
+    appName: 'gsd',
+    args: process.argv.slice(2),
+    cwd: process.cwd(),
+    agentDir,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    allowedCommands: new Set(['install', 'remove', 'list']),
+});
+if (packageCommand.handled) {
+    process.exit(packageCommand.exitCode);
+}
 // `gsd config` — replay the setup wizard and exit
 if (cliFlags.messages[0] === 'config') {
     const authStorage = AuthStorage.create(authFilePath);

package/dist/help-text.js

@@ -29,6 +29,27 @@ const SUBCOMMAND_HELP = {
         '',
         'Compare with --continue (-c) which always resumes the most recent session.',
     ].join('\n'),
+    install: [
+        'Usage: gsd install <source> [-l, --local]',
+        '',
+        'Install a package/extension source and run declared lifecycle hooks.',
+        '',
+        'Examples:',
+        '  gsd install npm:@foo/bar',
+        '  gsd install git:github.com/user/repo',
+        '  gsd install https://github.com/user/repo',
+        '  gsd install ./local/path',
+    ].join('\n'),
+    remove: [
+        'Usage: gsd remove <source> [-l, --local]',
+        '',
+        'Remove an installed package source and its settings entry.',
+    ].join('\n'),
+    list: [
+        'Usage: gsd list',
+        '',
+        'List installed package sources from user and project settings.',
+    ].join('\n'),
     worktree: [
         'Usage: gsd worktree <command> [args]',
         '',
@@ -122,6 +143,9 @@ export function printHelp(version) {
     process.stdout.write('  --help, -h               Print this help and exit\n');
     process.stdout.write('\nSubcommands:\n');
     process.stdout.write('  config                   Re-run the setup wizard\n');
+    process.stdout.write('  install <source>         Install a package/extension source\n');
+    process.stdout.write('  remove <source>          Remove an installed package source\n');
+    process.stdout.write('  list                     List installed package sources\n');
     process.stdout.write('  update                   Update GSD to the latest version\n');
     process.stdout.write('  sessions                 List and resume a past session\n');
     process.stdout.write('  worktree <cmd>           Manage worktrees (list, merge, clean, remove)\n');

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -13,7 +13,7 @@
 import { deriveState } from "./state.js";
 import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
-import { resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveMilestoneFile, resolveTasksDir, buildTaskFileName, gsdRoot, } from "./paths.js";
+import { resolveSliceFile, resolveTaskFile, resolveMilestoneFile, resolveTasksDir, buildTaskFileName, gsdRoot, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { autoCommitCurrentBranch, } from "./worktree.js";
@@ -22,13 +22,13 @@ import { writeUnitRuntimeRecord, clearUnitRuntimeRecord } from "./unit-runtime.j
 import { runGSDDoctor, rebuildState, summarizeDoctorIssues } from "./doctor.js";
 import { recordHealthSnapshot, checkHealEscalation } from "./doctor-proactive.js";
 import { syncStateToProjectRoot } from "./auto-worktree-sync.js";
-import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter } from "./gsd-db.js";
 import { renderPlanCheckboxes } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import { checkPostUnitHooks, isRetryPending, consumeRetryTrigger, persistHookState, resolveHookArtifactPath, } from "./post-unit-hooks.js";
 import { hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { debugLog } from "./debug-logger.js";
-import { existsSync, unlinkSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteSync } from "./atomic-write.js";
 import { _resetHasChangesCache } from "./native-git-bridge.js";
@@ -101,6 +101,39 @@ export function detectRogueFileWrites(unitType, unitId, basePath) {
         if (!hasPlanningState) {
             rogues.push({ path: planPath, unitType, unitId });
         }
+        // Also check for rogue REPLAN.md
+        const replanPath = resolveSliceFile(basePath, mid, sid, "REPLAN");
+        if (replanPath && existsSync(replanPath) && !hasPlanningState) {
+            rogues.push({ path: replanPath, unitType, unitId });
+        }
+    }
+    else if (unitType === "reassess-roadmap") {
+        const [mid, sid] = parts;
+        if (!mid || !sid)
+            return [];
+        const assessPath = resolveSliceFile(basePath, mid, sid, "ASSESSMENT");
+        if (!assessPath || !existsSync(assessPath))
+            return [];
+        // Assessment file exists on disk — check if DB knows about it via the artifacts table
+        const adapter = _getAdapter();
+        if (adapter) {
+            const row = adapter.prepare(`SELECT 1 FROM artifacts WHERE path LIKE :pattern AND artifact_type = 'ASSESSMENT' LIMIT 1`).get({ ":pattern": `%${sid}-ASSESSMENT.md` });
+            if (!row) {
+                rogues.push({ path: assessPath, unitType, unitId });
+            }
+        }
+    }
+    else if (unitType === "plan-task") {
+        const [mid, sid, tid] = parts;
+        if (!mid || !sid || !tid)
+            return [];
+        const taskPlanPath = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+        if (!taskPlanPath || !existsSync(taskPlanPath))
+            return [];
+        const dbRow = getTask(mid, sid, tid);
+        if (!dbRow) {
+            rogues.push({ path: taskPlanPath, unitType, unitId });
+        }
     }
     return rogues;
 }
@@ -468,26 +501,10 @@ export async function postUnitPostVerification(pctx) {
                             updateTaskStatus(mid, sid, tid, "pending");
                             await renderPlanCheckboxes(s.basePath, mid, sid);
                         }
-                        catch {
-                            // DB may be unavailable — fall back to direct file-based uncheck
-                            try {
-                                const slicePath = resolveSlicePath(s.basePath, mid, sid);
-                                if (slicePath) {
-                                    const { readdirSync } = await import("node:fs");
-                                    const planCandidates = readdirSync(slicePath)
-                                        .filter((f) => f.includes("PLAN") && (f.startsWith(sid) || f.startsWith(`${sid}-`)));
-                                    if (planCandidates.length > 0) {
-                                        const planFile = join(slicePath, planCandidates[0]);
-                                        let content = readFileSync(planFile, "utf-8");
-                                        const regex = new RegExp(`^(\\s*-\\s*)\\[x\\](\\s*\\**${tid}\\**[:\\s])`, "mi");
-                                        if (regex.test(content)) {
-                                            content = content.replace(regex, "$1[ ]$2");
-                                            writeFileSync(planFile, content, "utf-8");
-                                        }
-                                    }
-                                }
-                            }
-                            catch { /* non-fatal: file-based fallback failure */ }
+                        catch (dbErr) {
+                            // DB unavailable — fail explicitly rather than silently reverting to markdown mutation.
+                            // Use 'gsd recover' to rebuild DB state from disk if needed.
+                            process.stderr.write(`gsd: retry state-reset failed (DB unavailable): ${dbErr.message}. Run 'gsd recover' to reconcile.\n`);
                         }
                     }
                     // 2. Delete SUMMARY.md for the task

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -284,10 +284,10 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
                     return false;
             }
             else if (!isDbAvailable()) {
-                // DB unavailable — fall back to plan heading check (format detection,
-                // not reconciliation). Heading-style entries (### T01 --) count as
-                // verified because the summary file existence (checked above) is the
-                // real signal.
+                // LEGACY: Pre-migration fallback for projects without DB.
+                // Fall back to plan heading check (format detection, not reconciliation).
+                // Heading-style entries (### T01 --) count as verified because the
+                // summary file existence (checked above) is the real signal.
                 const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
                 if (planAbs && existsSync(planAbs)) {
                     const planContent = readFileSync(planAbs, "utf-8");
@@ -320,7 +320,7 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
                         taskIds = tasks.map(t => t.id);
                 }
                 if (!taskIds) {
-                    // DB unavailable or no tasks in DB — parse plan file for task IDs
+                    // LEGACY: DB unavailable or no tasks in DB — parse plan file for task IDs
                     const planContent = readFileSync(absPath, "utf-8");
                     const plan = parseLegacyPlan(planContent);
                     if (plan.tasks.length > 0)
@@ -362,7 +362,8 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
                     return false;
             }
             else if (!isDbAvailable()) {
-                // DB unavailable — fall back to roadmap checkbox check via parsers-legacy
+                // LEGACY: Pre-migration fallback for projects without DB.
+                // Fall back to roadmap checkbox check via parsers-legacy
                 const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
                 if (roadmapFile && existsSync(roadmapFile)) {
                     try {

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

@@ -667,6 +667,71 @@ export function registerDbTools(pi) {
     };
     pi.registerTool(sliceCompleteTool);
     registerAlias(pi, sliceCompleteTool, "gsd_complete_slice", "gsd_slice_complete");
+    // ─── gsd_complete_milestone ────────────────────────────────────────────
+    const milestoneCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot complete milestone." }],
+                details: { operation: "complete_milestone", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleCompleteMilestone } = await import("../tools/complete-milestone.js");
+            const result = await handleCompleteMilestone(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error completing milestone: ${result.error}` }],
+                    details: { operation: "complete_milestone", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}` }],
+                details: {
+                    operation: "complete_milestone",
+                    milestoneId: result.milestoneId,
+                    summaryPath: result.summaryPath,
+                },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`gsd-db: complete_milestone tool failed: ${msg}\n`);
+            return {
+                content: [{ type: "text", text: `Error completing milestone: ${msg}` }],
+                details: { operation: "complete_milestone", error: msg },
+            };
+        }
+    };
+    const milestoneCompleteTool = {
+        name: "gsd_complete_milestone",
+        label: "Complete Milestone",
+        description: "Record a completed milestone to the GSD database, render MILESTONE-SUMMARY.md to disk — all in one atomic operation. " +
+            "Validates all slices are complete before proceeding.",
+        promptSnippet: "Complete a GSD milestone (DB write + summary render)",
+        promptGuidelines: [
+            "Use gsd_complete_milestone when all slices in a milestone are finished and the milestone needs to be recorded.",
+            "All slices in the milestone must have status 'complete' — the handler validates this before proceeding.",
+            "On success, returns summaryPath where the MILESTONE-SUMMARY.md was written.",
+        ],
+        parameters: Type.Object({
+            milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+            title: Type.String({ description: "Milestone title" }),
+            oneLiner: Type.String({ description: "One-sentence summary of what the milestone achieved" }),
+            narrative: Type.String({ description: "Detailed narrative of what happened during the milestone" }),
+            successCriteriaResults: Type.String({ description: "Markdown detailing how each success criterion was met or not met" }),
+            definitionOfDoneResults: Type.String({ description: "Markdown detailing how each definition-of-done item was met" }),
+            requirementOutcomes: Type.String({ description: "Markdown detailing requirement status transitions with evidence" }),
+            keyDecisions: Type.Array(Type.String(), { description: "Key architectural/pattern decisions made during the milestone" }),
+            keyFiles: Type.Array(Type.String(), { description: "Key files created or modified during the milestone" }),
+            lessonsLearned: Type.Array(Type.String(), { description: "Lessons learned during the milestone" }),
+            followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })),
+            deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })),
+        }),
+        execute: milestoneCompleteExecute,
+    };
+    pi.registerTool(milestoneCompleteTool);
+    registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
     // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
     const replanSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const dbAvailable = await ensureDbOpen();

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

@@ -43,12 +43,29 @@ export async function handleCleanupBranches(ctx, basePath) {
         const { loadFile } = await import("./files.js");
         const { parseRoadmap } = await import("./parsers-legacy.js");
         const { isMilestoneComplete } = await import("./state.js");
+        const { isDbAvailable, getMilestone } = await import("./gsd-db.js");
         const attachedBranches = new Set(listWorktrees(basePath).map((wt) => wt.branch));
         const milestoneBranches = nativeBranchList(basePath, "milestone/*");
         for (const branch of milestoneBranches) {
             if (attachedBranches.has(branch))
                 continue;
             const milestoneId = branch.replace(/^milestone\//, "");
+            // DB-first: check milestone status directly
+            if (isDbAvailable()) {
+                const dbRow = getMilestone(milestoneId);
+                if (dbRow) {
+                    if (dbRow.status !== "complete" && dbRow.status !== "done")
+                        continue;
+                    // Milestone is complete per DB — proceed to delete branch
+                    try {
+                        nativeBranchDelete(basePath, branch, true);
+                        deletedStaleMilestones++;
+                    }
+                    catch { /* non-fatal */ }
+                    continue;
+                }
+            }
+            // Filesystem fallback
             const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
             if (!roadmapPath)
                 continue;
@@ -427,15 +444,14 @@ export async function handleRecover(ctx, basePath) {
         return;
     }
     try {
-        // 1. Delete hierarchy rows inside a transaction
+        // 1. Delete + re-populate inside a single transaction for atomicity
         const db = _getAdapter();
-        dbTransaction(() => {
+        const counts = dbTransaction(() => {
             db.exec("DELETE FROM tasks");
             db.exec("DELETE FROM slices");
             db.exec("DELETE FROM milestones");
+            return migrateHierarchyToDb(basePath);
         });
-        // 2. Re-populate from rendered markdown on disk
-        const counts = migrateHierarchyToDb(basePath);
         // 3. Invalidate state cache so deriveState() picks up fresh DB data
         invalidateStateCache();
         // 4. Derive state to verify sanity

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

@@ -265,7 +265,14 @@ export async function saveDecisionToDb(fields, basePath) {
             // Table format or no existing file — full regeneration (original behavior)
             md = generateDecisionsMd(allDecisions);
         }
-        await saveFile(filePath, md);
+        try {
+            await saveFile(filePath, md);
+        }
+        catch (diskErr) {
+            process.stderr.write(`gsd-db: saveDecisionToDb — disk write failed, rolling back DB row: ${diskErr.message}\n`);
+            adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
+            throw diskErr;
+        }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
         // Do NOT clear the artifacts table — we just wrote to it intentionally.
         invalidateStateCache();
@@ -322,7 +329,14 @@ export async function updateRequirementInDb(id, updates, basePath) {
         const nonSuperseded = allRequirements.filter(r => r.superseded_by == null);
         const md = generateRequirementsMd(nonSuperseded);
         const filePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
-        await saveFile(filePath, md);
+        try {
+            await saveFile(filePath, md);
+        }
+        catch (diskErr) {
+            process.stderr.write(`gsd-db: updateRequirementInDb — disk write failed, reverting DB row: ${diskErr.message}\n`);
+            db.upsertRequirement(existing);
+            throw diskErr;
+        }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
         // Do NOT clear the artifacts table — we just wrote to it intentionally.
         invalidateStateCache();
@@ -356,7 +370,15 @@ export async function saveArtifactToDb(opts, basePath) {
         if (!fullPath.startsWith(gsdDir)) {
             throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
         }
-        await saveFile(fullPath, opts.content);
+        try {
+            await saveFile(fullPath, opts.content);
+        }
+        catch (diskErr) {
+            process.stderr.write(`gsd-db: saveArtifactToDb — disk write failed, rolling back DB row: ${diskErr.message}\n`);
+            const rollbackAdapter = db._getAdapter();
+            rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
+            throw diskErr;
+        }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
         // Do NOT clear the artifacts table — we just wrote to it intentionally.
         invalidateStateCache();

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

@@ -109,6 +109,9 @@ const SCHEMA_VERSION = 10;
 function initSchema(db, fileBacked) {
     if (fileBacked)
         db.exec("PRAGMA journal_mode=WAL");
+    if (fileBacked)
+        db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA foreign_keys = ON");
     db.exec("BEGIN");
     try {
         db.exec(`
@@ -219,7 +222,7 @@ function initSchema(db, fileBacked) {
         proof_level TEXT NOT NULL DEFAULT '',
         integration_closure TEXT NOT NULL DEFAULT '',
         observability_impact TEXT NOT NULL DEFAULT '',
-        sequence INTEGER DEFAULT 0,
+        sequence INTEGER DEFAULT 0, -- DEAD CODE: no tool exposes sequence — always 0
         replan_triggered_at TEXT DEFAULT NULL,
         PRIMARY KEY (milestone_id, id),
         FOREIGN KEY (milestone_id) REFERENCES milestones(id)
@@ -250,7 +253,7 @@ function initSchema(db, fileBacked) {
         inputs TEXT NOT NULL DEFAULT '[]',
         expected_output TEXT NOT NULL DEFAULT '[]',
         observability_impact TEXT NOT NULL DEFAULT '',
-        sequence INTEGER DEFAULT 0,
+        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)
       )

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

@@ -24,7 +24,7 @@ Then:
 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, writes the slice summary to `{{sliceSummaryPath}}`, UAT to `{{sliceUatPath}}`, and toggles the `{{sliceId}}` checkbox in `{{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:
+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`
 
@@ -45,6 +45,6 @@ Then:
 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 toggling the `{{roadmapPath}}` checkbox atomically. You must still review decisions and knowledge manually (steps 7-8).
+**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).
 
 When done, say: "Slice {{sliceId}} complete."

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

@@ -202,7 +202,7 @@ Once the user is satisfied, in a single pass:
 When writing context.md, preserve the user's exact terminology, emphasis, and specific framing from the discussion. Do not paraphrase user nuance into generic summaries. If the user said "craft feel," write "craft feel" — not "high-quality user experience." If they emphasized a specific constraint or negative requirement, carry that emphasis through verbatim. The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
 
 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. Write `{{roadmapPath}}` — use the **Roadmap** output template below. Decompose into demoable vertical slices with checkboxes, 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.
+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.
 7. {{commitInstruction}}
 
@@ -222,7 +222,7 @@ Once the user confirms the milestone split:
 #### Phase 2: Primary milestone
 
 5. Write a full `CONTEXT.md` for the primary milestone (the one discussed in depth).
-6. Write a `ROADMAP.md` for **only the primary milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
+6. Call `gsd_plan_milestone` for **only the primary milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
 
 #### MANDATORY: depends_on Frontmatter in CONTEXT.md
 

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

@@ -63,7 +63,7 @@ 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 writes the summary file to `{{taskSummaryPath}}`, toggles the `[ ]` → `[x]` checkbox in `{{planPath}}`, and persists the task row to the DB. 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:
+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}}"
@@ -80,6 +80,6 @@ Then:
 
 All work stays in your working directory: `{{workingDirectory}}`.
 
-**You MUST call `gsd_task_complete` before finishing.** The tool handles writing `{{taskSummaryPath}}` and toggling the checkbox in `{{planPath}}` — do not write the summary file or toggle the checkbox manually.
+**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.
 
 When done, say: "Task {{taskId}} complete."

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

@@ -80,15 +80,13 @@ Apply these when decomposing and ordering slices:
 
 ## Single-Slice Fast Path
 
-If the roadmap has only one slice, also write the slice plan and task plans inline during this unit — don't leave them for a separate planning session.
+If the roadmap has only one slice, also plan the slice and its tasks inline during this unit — don't leave them for a separate planning session.
 
-1. Use the **Slice Plan** and **Task Plan** output templates from the inlined context above
-2. `mkdir -p {{milestonePath}}/slices/S01/tasks`
-3. Write the S01 plan file at `{{milestonePath}}/slices/S01/S01-PLAN.md`
-4. Write individual task plans at `{{milestonePath}}/slices/S01/tasks/T01-PLAN.md`, etc.
-5. For simple slices, keep the plan lean — omit Proof Level, Integration Closure, and Observability sections if they would all be "none". Executable verification commands are sufficient.
+1. After `gsd_plan_milestone` returns, immediately call `gsd_plan_slice` for S01 with the full task breakdown
+2. Use the **Slice Plan** and **Task Plan** output templates from the inlined context above to structure the tool call parameters
+3. For simple slices, keep the plan lean — omit Proof Level, Integration Closure, and Observability sections if they would all be "none". Executable verification commands are sufficient.
 
-This eliminates a separate research-slice + plan-slice cycle when the work is straightforward.
+Do **not** write plan files manually — use the DB-backed tools so state stays consistent.
 
 ## Secret Forecasting
 

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

@@ -1,5 +1,5 @@
 // GSD Extension — State Derivation
-// Reads roadmap + plan files to determine current position.
+// DB-primary state derivation with filesystem fallback for unmigrated projects.
 // Pure TypeScript, zero Pi dependencies.
 import { parseRoadmap, parsePlan, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
@@ -68,40 +68,48 @@ export function invalidateStateCache() {
  * Returns the ID of the first incomplete milestone, or null if all are complete.
  */
 export async function getActiveMilestoneId(basePath) {
-    const milestoneIds = findMilestoneIds(basePath);
     // Parallel worker isolation
     const milestoneLock = process.env.GSD_MILESTONE_LOCK;
     if (milestoneLock) {
+        const milestoneIds = findMilestoneIds(basePath);
         if (!milestoneIds.includes(milestoneLock))
             return null;
-        // Locked milestone that is parked should not be active
         const lockedParked = resolveMilestoneFile(basePath, milestoneLock, "PARKED");
         if (lockedParked)
             return null;
         return milestoneLock;
     }
+    // DB-first: query milestones table for the first non-complete, non-parked milestone
+    if (isDbAvailable()) {
+        const allMilestones = getAllMilestones();
+        if (allMilestones.length > 0) {
+            const sorted = [...allMilestones].sort((a, b) => a.id.localeCompare(b.id));
+            for (const m of sorted) {
+                if (m.status === "complete" || m.status === "done" || m.status === "parked")
+                    continue;
+                return m.id;
+            }
+            return null;
+        }
+    }
+    // Filesystem fallback for unmigrated projects or empty DB
+    const milestoneIds = findMilestoneIds(basePath);
     for (const mid of milestoneIds) {
-        // Skip parked milestones — they are not eligible for active status
         const parkedFile = resolveMilestoneFile(basePath, mid, "PARKED");
         if (parkedFile)
             continue;
         const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
         const content = roadmapFile ? await loadFile(roadmapFile) : null;
         if (!content) {
-            // No roadmap — but if a summary exists, the milestone is already complete
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
             if (summaryFile)
-                continue; // completed milestone, skip
+                continue;
             if (isGhostMilestone(basePath, mid))
-                continue; // ghost dir — skip
-            return mid; // No roadmap and no summary — milestone is incomplete
-            // Note: draft-awareness (CONTEXT-DRAFT.md) is handled in deriveState(), not here.
-            // A draft milestone is still "active" — this function only determines which milestone is current.
+                continue;
+            return mid;
         }
         const roadmap = parseRoadmap(content);
         if (!isMilestoneComplete(roadmap)) {
-            // Summary is the terminal artifact — if it exists, the milestone is
-            // complete even when roadmap checkboxes weren't ticked (#864).
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
             if (!summaryFile)
                 return mid;
@@ -110,13 +118,12 @@ export async function getActiveMilestoneId(basePath) {
     return null;
 }
 /**
- * Reconstruct GSD state from files on disk.
- * This is the source of truth — STATE.md is just a cache of this output.
+ * Reconstruct GSD state from DB (primary) or filesystem (fallback).
+ * STATE.md is a rendered cache of this output.
  *
- * Uses native batch parsing when available: a single Rust call reads and parses
- * every .md file under .gsd/, populating an in-memory cache that replaces all
- * individual loadFile() calls during milestone/slice/task traversal.
- * Falls back to sequential JS file reads when the native module is absent.
+ * When DB is available, queries milestone/slice/task tables directly.
+ * Falls back to filesystem parsing for unmigrated projects or when DB
+ * has zero milestones (e.g. first run before migration).
  */
 export async function deriveState(basePath) {
     // Return cached result if within the TTL window for the same basePath
@@ -590,6 +597,9 @@ export async function deriveStateFromDb(basePath) {
         progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
     };
 }
+// LEGACY: Filesystem-based state derivation for unmigrated projects.
+// DB-backed projects use deriveStateFromDb() above. Target: extract to
+// state-legacy.ts when all projects are DB-backed.
 export async function _deriveStateImpl(basePath) {
     const milestoneIds = findMilestoneIds(basePath);
     // ── Parallel worker isolation ──────────────────────────────────────────