gsd-pi 2.82.0 → 3.0.0

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -1,10 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
-import { clearEngineHierarchy, getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, transaction, } from "./gsd-db.js";
-import { migrateHierarchyToDb } from "./md-importer.js";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, } from "./gsd-db.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
 import { milestonesDir, resolveMilestoneFile, resolveSliceFile, } from "./paths.js";
-import { invalidateStateCache } from "./state.js";
 function zeroCounts() {
     return { milestones: 0, slices: 0, tasks: 0 };
 }
@@ -50,7 +48,7 @@ export function countDbHierarchy() {
     }
     return counts;
 }
-export async function autoImportMarkdownHierarchyIfDbMismatch(basePath) {
+export async function checkMarkdownHierarchyAgainstDb(basePath) {
     const markdown = countMarkdownHierarchy(basePath);
     if (sameCounts(markdown, zeroCounts())) {
         return {
@@ -70,18 +68,15 @@ export async function autoImportMarkdownHierarchyIfDbMismatch(basePath) {
         return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };
     }
     const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
-    const imported = transaction(() => {
-        clearEngineHierarchy();
-        return migrateHierarchyToDb(basePath);
-    });
-    invalidateStateCache();
-    const afterDb = {
-        milestones: imported.milestones,
-        slices: imported.slices,
-        tasks: imported.tasks,
+    return {
+        action: "recovery-required",
+        reason,
+        markdown,
+        beforeDb,
+        afterDb: beforeDb,
+        recoveryCommand: "gsd recover",
+        message: `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
+            `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). ` +
+            "Runtime startup will not import markdown automatically; run explicit GSD recovery if markdown should repopulate the database.",
     };
-    if (!sameCounts(markdown, afterDb)) {
-        throw new Error(`migration auto-import verification failed: markdown ${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T, db ${afterDb.milestones}M/${afterDb.slices}S/${afterDb.tasks}T`);
-    }
-    return { action: "imported", reason, markdown, beforeDb, afterDb };
 }

package/dist/resources/extensions/gsd/milestone-actions.js

@@ -19,6 +19,7 @@ import { deleteMilestone, getMilestone, isDbAvailable, updateMilestoneStatus } f
 import { removeWorktree } from "./worktree-manager.js";
 import { logWarning } from "./workflow-logger.js";
 import { isAutoActive } from "./auto.js";
+import { isClosedStatus } from "./status-guards.js";
 /**
  * Writer-side assert for mutations that race with auto-mode's squash merge (#4704).
  * Auto-mode is confirmed not to call parkMilestone/discardMilestone/unparkMilestone
@@ -34,7 +35,7 @@ function assertNotAutoActive(action) {
 /**
  * Park a milestone — creates a PARKED.md marker file with reason and timestamp.
  * Parked milestones are skipped during active-milestone discovery but stay on disk.
- * Returns true if successfully parked, false if milestone not found or already parked.
+ * Returns true if successfully parked, false if milestone not found, already parked, or complete.
  */
 export function parkMilestone(basePath, milestoneId, reason) {
     assertNotAutoActive("park milestone");
@@ -42,9 +43,15 @@ export function parkMilestone(basePath, milestoneId, reason) {
     if (!mDir || !existsSync(mDir))
         return false;
     // Guard: do not park a completed milestone — it would corrupt depends_on satisfaction
-    const summaryFile = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
-    if (summaryFile)
+    const dbAvailable = isDbAvailable();
+    const milestone = dbAvailable ? getMilestone(milestoneId) : null;
+    if (milestone && isClosedStatus(milestone.status))
         return false;
+    if (!dbAvailable) {
+        const summaryFile = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+        if (summaryFile)
+            return false;
+    }
     const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
     if (existsSync(parkedPath))
         return false; // already parked
@@ -61,7 +68,7 @@ export function parkMilestone(basePath, milestoneId, reason) {
     ].join("\n");
     writeFileSync(parkedPath, content, "utf-8");
     // Sync DB status so deriveStateFromDb also skips this milestone (#2694)
-    if (isDbAvailable()) {
+    if (dbAvailable) {
         try {
             updateMilestoneStatus(milestoneId, "parked");
         }

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -14,6 +14,8 @@ import { isInfrastructureError } from "./auto/infra-errors.js";
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
 const NATIVE_GSD_GIT_ENABLED = process.env.GSD_ENABLE_NATIVE_GSD_GIT === "1";
+const TRANSIENT_GIT_RETRY_CODES = new Set(["ENOBUFS", "EAGAIN"]);
+const GIT_RETRY_DELAY_MS = 200;
 // ─── Native Module Loading ──────────────────────────────────────────────────
 let nativeModule = null;
 let loadAttempted = false;
@@ -46,10 +48,42 @@ function gitExec(basePath, args, allowFailure = false) {
             env: GIT_NO_PROMPT_ENV,
         }).trim();
     }
-    catch {
+    catch (err) {
         if (allowFailure)
             return "";
-        throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}`);
+        throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}: ${getErrorMessage(err)}`);
+    }
+}
+/** sleepSync uses Atomics.wait for a blocking pause without busy-waiting; it blocks the current thread and requires Atomics.wait support. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isRetryableGitError(err) {
+    const code = isInfrastructureError(err)
+        ?? isInfrastructureError(err?.stderr ?? "");
+    return code !== null && TRANSIENT_GIT_RETRY_CODES.has(code);
+}
+function execGitFileSyncWithRetry(basePath, args, options) {
+    try {
+        return execFileSync("git", args, {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+            ...options,
+        }).trim();
+    }
+    catch (err) {
+        if (!isRetryableGitError(err))
+            throw err;
+        sleepSync(GIT_RETRY_DELAY_MS);
+        return execFileSync("git", args, {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+            ...options,
+        }).trim();
     }
 }
 /** Run a git command via execFileSync. Returns trimmed stdout. */
@@ -62,10 +96,10 @@ function gitFileExec(basePath, args, allowFailure = false) {
             env: GIT_NO_PROMPT_ENV,
         }).trim();
     }
-    catch {
+    catch (err) {
         if (allowFailure)
             return "";
-        throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}`);
+        throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}: ${getErrorMessage(err)}`);
     }
 }
 // ─── Existing Read Functions ──────────────────────────────────────────────
@@ -303,15 +337,20 @@ export function nativeDiffNameStatus(basePath, fromRef, toRef, pathspec, useMerg
 }
 /**
  * Get numstat diff between two refs.
+ * useMergeBase: if true, uses three-dot semantics.
  * Native: libgit2 patch line stats.
  * Fallback: `git diff --numstat`.
  */
-export function nativeDiffNumstat(basePath, fromRef, toRef) {
+export function nativeDiffNumstat(basePath, fromRef, toRef, useMergeBase) {
     const native = loadNative();
-    if (native) {
+    if (native && !useMergeBase) {
         return native.gitDiffNumstat(basePath, fromRef, toRef);
     }
-    const result = gitExec(basePath, ["diff", "--numstat", fromRef, toRef], true);
+    const refspec = useMergeBase ? `${fromRef}...${toRef}` : undefined;
+    const args = refspec
+        ? ["diff", "--numstat", refspec]
+        : ["diff", "--numstat", fromRef, toRef];
+    const result = gitExec(basePath, args, true);
     if (!result)
         return [];
     return result.split("\n").filter(Boolean).map(line => {
@@ -777,13 +816,10 @@ export function nativeCommit(basePath, message, options) {
         const args = ["commit", "-F", "-"];
         if (options?.allowEmpty)
             args.push("--allow-empty");
-        const result = execFileSync("git", args, {
-            cwd: basePath,
+        const result = execGitFileSyncWithRetry(basePath, args, {
             stdio: ["pipe", "pipe", "pipe"],
-            encoding: "utf-8",
-            env: GIT_NO_PROMPT_ENV,
             input: message,
-        }).trim();
+        });
         return result;
     }
     catch (err) {

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

@@ -320,6 +320,10 @@ export function resolveGsdPathContract(workRoot, originalProjectRoot) {
         isWorktree,
     };
 }
+export function gsdProjectionRoot(basePath) {
+    const contract = resolveGsdPathContract(basePath);
+    return normalizeRealPath(contract.worktreeGsd ?? contract.projectGsd);
+}
 /**
  * Invalidate the gsdRoot cache.
  * Use ONLY at session-reset boundaries: workspace switch, process exit, or

package/dist/resources/extensions/gsd/pending-auto-start.js

@@ -0,0 +1,52 @@
+// GSD-2 — Pending auto-start handoff state.
+// Stores discuss-to-auto handoff entries keyed by project root.
+import { createWorkspace, scopeMilestone } from "./workspace.js";
+const pendingAutoStartMap = new Map();
+export function getPendingAutoStart(basePath) {
+    if (basePath)
+        return pendingAutoStartMap.get(basePath) ?? null;
+    if (pendingAutoStartMap.size === 1)
+        return pendingAutoStartMap.values().next().value;
+    return null;
+}
+export const _getPendingAutoStart = getPendingAutoStart;
+export function hasPendingAutoStart(basePath) {
+    if (basePath)
+        return pendingAutoStartMap.has(basePath);
+    return pendingAutoStartMap.size > 0;
+}
+export function setPendingAutoStart(basePath, entry) {
+    if (!entry.ctx || !entry.pi) {
+        throw new Error("setPendingAutoStart requires ctx and pi");
+    }
+    const ws = createWorkspace(entry.basePath);
+    const scope = scopeMilestone(ws, entry.milestoneId);
+    pendingAutoStartMap.set(basePath, {
+        createdAt: Date.now(),
+        planBlockedRecoveryCount: 0,
+        ...entry,
+        scope,
+        ctx: entry.ctx,
+        pi: entry.pi,
+    });
+}
+export function deletePendingAutoStart(basePath) {
+    pendingAutoStartMap.delete(basePath);
+}
+export function clearPendingAutoStart(basePath) {
+    if (basePath) {
+        pendingAutoStartMap.delete(basePath);
+    }
+    else {
+        pendingAutoStartMap.clear();
+    }
+}
+export function getDiscussionMilestoneId(basePath) {
+    if (basePath) {
+        return pendingAutoStartMap.get(basePath)?.milestoneId ?? null;
+    }
+    if (pendingAutoStartMap.size === 1) {
+        return pendingAutoStartMap.values().next().value.milestoneId;
+    }
+    return null;
+}

package/dist/resources/extensions/gsd/post-execution-checks.js

@@ -17,6 +17,43 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, dirname, extname } from "node:path";
 // ─── Import Resolution Check ─────────────────────────────────────────────────
+/**
+ * Replace the contents of single- and double-quoted string literals on a single
+ * source line with spaces so import patterns do not match text inside strings.
+ * Template-literal spans are handled separately via the inTemplateLiteral flag.
+ */
+function stripStringLiterals(line) {
+    let result = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '"' || ch === "'") {
+            result += ch;
+            i++;
+            while (i < line.length) {
+                const c = line[i];
+                if (c === "\\" && i + 1 < line.length) {
+                    result += "  ";
+                    i += 2;
+                }
+                else if (c === ch) {
+                    result += ch;
+                    i++;
+                    break;
+                }
+                else {
+                    result += " ";
+                    i++;
+                }
+            }
+        }
+        else {
+            result += ch;
+            i++;
+        }
+    }
+    return result;
+}
 /**
  * Extract relative import paths from TypeScript/JavaScript source code.
  * Returns array of { importPath, lineNum } for relative imports.
@@ -30,11 +67,19 @@ export function extractRelativeImports(source) {
     //   import './path'
     //   require('./path')
     //   require("../path")
-    const importPattern = /(?:import\s+(?:.*?\s+from\s+)?|require\s*\(\s*)(['"])(\.\.?\/[^'"]+)\1/g;
+    const importPattern = /(?:^|[;{}]\s*)import\s+(?:.*?\s+from\s+)?(['"])(\.\.?\/[^'"]+)\1/g;
+    const requirePattern = /require\s*\(\s*(['"])(\.\.?\/[^'"]+)\1/g;
     // Track if we're inside a block comment
     let inBlockComment = false;
+    let inTemplateLiteral = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        if (inTemplateLiteral) {
+            if ((line.match(/(?<!\\)`/g) ?? []).length % 2 === 1) {
+                inTemplateLiteral = false;
+            }
+            continue;
+        }
         // Handle block comment boundaries
         if (inBlockComment) {
             if (line.includes("*/")) {
@@ -61,9 +106,17 @@ export function extractRelativeImports(source) {
         let match;
         // Reset lastIndex for each line
         importPattern.lastIndex = 0;
+        requirePattern.lastIndex = 0;
+        const strippedLine = stripStringLiterals(line);
         while ((match = importPattern.exec(line)) !== null) {
+            const importOffset = match[0].indexOf("import");
+            const importStart = match.index + importOffset;
+            if (strippedLine.slice(importStart, importStart + "import".length) !==
+                "import") {
+                continue;
+            }
             // Check if this match is after a // comment marker on the same line
-            const beforeMatch = line.substring(0, match.index);
+            const beforeMatch = strippedLine.substring(0, match.index);
             if (beforeMatch.includes("//")) {
                 continue;
             }
@@ -72,6 +125,24 @@ export function extractRelativeImports(source) {
                 lineNum: i + 1,
             });
         }
+        while ((match = requirePattern.exec(line)) !== null) {
+            if (strippedLine.slice(match.index, match.index + "require".length) !==
+                "require") {
+                continue;
+            }
+            // Check if this match is after a // comment marker on the same line
+            const beforeMatch = strippedLine.substring(0, match.index);
+            if (beforeMatch.includes("//")) {
+                continue;
+            }
+            imports.push({
+                importPath: match[2],
+                lineNum: i + 1,
+            });
+        }
+        if ((strippedLine.match(/(?<!\\)`/g) ?? []).length % 2 === 1) {
+            inTemplateLiteral = true;
+        }
     }
     return imports;
 }

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -19,7 +19,33 @@ import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { validateVerificationCommand } from "./verification-gate.js";
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
+export function checkVerificationCommands(tasks) {
+    const results = [];
+    for (const task of tasks) {
+        const verify = task.verify.trim();
+        if (!verify)
+            continue;
+        const commands = verify
+            .split("&&")
+            .map((command) => command.trim())
+            .filter(Boolean);
+        for (const command of commands) {
+            const validation = validateVerificationCommand(command);
+            if (!validation.ok) {
+                results.push({
+                    category: "tool",
+                    target: `${task.id} Verify`,
+                    passed: false,
+                    message: `Unsafe or non-runnable Verify command: ${command} (${validation.reason})`,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
 // ─── Package Existence Check ─────────────────────────────────────────────────
 /**
  * Extract npm package names from task descriptions.
@@ -647,7 +673,8 @@ export async function runPreExecutionChecks(tasks, basePath) {
     const fileChecks = checkFilePathConsistency(tasks, basePath);
     const orderingChecks = checkTaskOrdering(tasks, basePath);
     const contractChecks = checkInterfaceContracts(tasks, basePath);
-    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks);
+    const verificationChecks = checkVerificationCommands(tasks);
+    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
     // Run async package checks
     const packageChecks = await checkPackageExistence(tasks, basePath);
     allChecks.push(...packageChecks);

package/dist/resources/extensions/gsd/prompt-loader.js

@@ -181,7 +181,7 @@ export function loadPrompt(name, vars = {}) {
             .map(m => m.slice(2, -2))
             .filter(key => !(key in effectiveVars));
         if (missing.length > 0) {
-            throw new GSDError(GSD_PARSE_ERROR, `loadPrompt("${name}"): template declares {{${missing.join("}}, {{")}}}} but no value was provided. ` +
+            throw new GSDError(GSD_PARSE_ERROR, `loadPrompt("${name}"): template declares {{${missing.join("}}, {{")}}} but no value was provided. ` +
                 `This usually means the extension code in memory is older than the template on disk. ` +
                 `Restart pi to reload the extension.`);
         }

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

@@ -57,7 +57,7 @@ Subagents report only; they do not write user source. Fold any findings into Dec
 **Success path** (all verifications passed):
 
 10. For each requirement whose status changed in step 9, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted.
-11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
+11. Refresh the project state through `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Do not write or edit `.gsd/PROJECT.md` directly.
 12. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
 
 {{extractLearningsSteps}}

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

@@ -34,7 +34,7 @@ Use `subagent` only for fresh-context review when useful: reviewer for cross-cut
 12. Review the inlined task-summary excerpts for DECISIONS.md and KNOWLEDGE.md-worthy decisions, patterns, and gotchas. Read full `*-SUMMARY.md` files only when an excerpt is absent, truncated, or lacks the specific evidence needed for the slice narrative. Capture significant items with `capture_thought`; do not append knowledge files directly.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes; the tool renders files and updates projections.
 14. Do not run git commands.
-15. Update `.gsd/PROJECT.md` with a full `write` only if the current project state needs refresh.
+15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.
 
 **Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
 

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

@@ -106,8 +106,8 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside content
 
 In a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
-2. Write or update `.gsd/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm states, ownership, and traceability before roadmap creation.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Describe what the project is, its current state, and list the milestone sequence.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Confirm states, ownership, and traceability before roadmap creation.
 
 **Depth-Preservation Guidance for context.md:** Preserve the specification's exact terminology, emphasis, and framing. Do not flatten domain-specific language into generics. CONTEXT.md is downstream agents' only window into this spec.
 
@@ -120,8 +120,8 @@ In a single pass:
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md` (step 2)
-- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (step 2)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (step 3)
 - [ ] Written `{{contextPath}}` (step 4)
 - [ ] Called `gsd_plan_milestone` (step 5)
 
@@ -145,8 +145,8 @@ Next steps:
 #### Phase 1: Shared artifacts
 
 1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. 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.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content so the tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. 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. For any architectural or pattern decisions, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 #### Phase 2: Primary milestone
@@ -214,8 +214,8 @@ For single-milestone projects, do NOT write this file.
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md`
-- [ ] Written `.gsd/REQUIREMENTS.md`
+- [ ] Called `gsd_summary_save` for the PROJECT artifact
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact
 - [ ] Written the primary milestone `CONTEXT.md`
 - [ ] Called `gsd_plan_milestone` for the primary milestone
 - [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`

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

@@ -186,7 +186,7 @@ Research is advisory, not auto-binding. Use discussion output to identify table
 
 ## Capability Contract
 
-Before writing a roadmap, produce or update `.gsd/REQUIREMENTS.md`.
+Before writing a roadmap, persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then render `.gsd/REQUIREMENTS.md` through `gsd_summary_save` with `artifact_type: "REQUIREMENTS"`.
 
 Use it as the project's explicit capability contract.
 
@@ -226,8 +226,8 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file co
 
 Once the user is satisfied, in a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
-2. Write or update `.gsd/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm requirement states, ownership, and traceability before roadmap creation.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Describe what the project is, its current state, and list the milestone sequence.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Confirm requirement states, ownership, and traceability before roadmap creation.
 **Depth-Preservation Guidance for context.md:**
 When writing context.md, preserve the user's exact terminology, emphasis, and framing. Do not flatten nuance into generic summaries. If the user said "craft feel," write "craft feel," not "high-quality user experience." CONTEXT.md is downstream agents' only window into this conversation.
 
@@ -243,8 +243,8 @@ When writing CONTEXT.md, include discussion-layer sections: **Scope**, **Archite
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md` (step 2)
-- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (step 2)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (step 3)
 - [ ] Written `{{contextPath}}` (step 4)
 - [ ] Called `gsd_plan_milestone` (step 5)
 
@@ -270,8 +270,8 @@ Once the user confirms the milestone split:
 #### Phase 1: Shared artifacts
 
 1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. 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.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content so the tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. 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. 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
@@ -344,8 +344,8 @@ For single-milestone projects, do NOT write this file.
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md` (Phase 1)
-- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (Phase 1)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (Phase 1)
 - [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
 - [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
 - [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)

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

@@ -1,6 +1,6 @@
 **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` elsewhere. For `.gsd` files, use absolute paths rooted at `{{workingDirectory}}`, not `Glob`.
 
-Discuss the **project** as a whole: vision, users, anti-goals, constraints, and rough milestone sequence. Ask only real gray areas, then write `.gsd/PROJECT.md` with the **Project** template below. If a `GSD Skill Preferences` block exists, use it; artifact rules still apply.
+Discuss the **project** as a whole: vision, users, anti-goals, constraints, and rough milestone sequence. Ask only real gray areas, then persist the final Project template through `gsd_summary_save` with `artifact_type: "PROJECT"`. The tool renders `.gsd/PROJECT.md`; do not write the projection directly. If a `GSD Skill Preferences` block exists, use it; artifact rules still apply.
 
 This runs once before milestone discussion. Later milestones, requirements, and roadmaps depend on it.
 
@@ -34,7 +34,7 @@ After the opening answer, classify project shape as **`simple`** or **`complex`*
 
 **Default to `complex` when uncertain.** The user can override the verdict in plain text; if they do, accept it and proceed.
 
-Persist the verdict to PROJECT.md -> `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read it from there.
+Persist the verdict through `gsd_summary_save` with `artifact_type: "PROJECT"` into `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read the rendered projection.
 
 ### Before deeper rounds
 
@@ -95,7 +95,7 @@ If they clarify, absorb the correction and re-verify.
 
 The depth verification is the only required confirmation gate. Do not add a second "ready to proceed?" gate after it.
 
-**CRITICAL — Confirmation gate:** Do not write final PROJECT.md until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, re-ask.
+**CRITICAL — Confirmation gate:** Do not persist final PROJECT content until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, re-ask.
 
 ---
 
@@ -104,7 +104,7 @@ The depth verification is the only required confirmation gate. Do not add a seco
 Once the user confirms depth:
 
 1. Use the **Project** output template (inlined above).
-2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool writes `.gsd/PROJECT.md` and persists to DB. Preserve the user's terms and framing.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Preserve the user's terms and framing.
 3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
 4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
 5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.

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

@@ -1,6 +1,6 @@
 **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` elsewhere. For `.gsd` files, use absolute paths rooted at `{{workingDirectory}}`, not `Glob`.
 
-Discuss **project-level requirements**. Read `.gsd/PROJECT.md` first; it is authoritative for vision, core value, anti-goals, and milestone sequence. Requirements must trace to it. Ask capability gray areas, then write `.gsd/REQUIREMENTS.md` using v2 `R###` format and the **Requirements** template.
+Discuss **project-level requirements**. Read `.gsd/PROJECT.md` first; it is the rendered project artifact for vision, core value, anti-goals, and milestone sequence. Requirements must trace to it. Ask capability gray areas, then persist requirements with `gsd_requirement_save` and render `.gsd/REQUIREMENTS.md` through `gsd_summary_save` using v2 `R###` format and the **Requirements** template.
 
 This runs once after `discuss-project` and before milestone work, creating the capability contract for milestones, slices, and verification.
 
@@ -25,7 +25,7 @@ Before your first action, print this banner verbatim in chat:
 3. If `.gsd/REQUIREMENTS.md` exists, read it as the working set.
 
 **Shape-dependent cadence:**
-- **`simple`**: one fast pass. Extract from PROJECT.md, ask 1-2 plain-text clarifiers only when class/status is ambiguous, then write REQUIREMENTS.md.
+- **`simple`**: one fast pass. Extract from PROJECT.md, ask 1-2 plain-text clarifiers only when class/status is ambiguous, then persist requirements through the DB-backed tools.
 - **`complex`**: multi-round questioning with structured 3-4-option questions where alternatives matter.
 
 ---
@@ -81,7 +81,7 @@ Before the wrap-up gate, verify: every milestone has an Active requirement; Core
 
 If they adjust, absorb and re-verify.
 
-**CRITICAL — Confirmation gate:** Do not write final REQUIREMENTS.md until explicit confirmation. Never rationalize past it.
+**CRITICAL — Confirmation gate:** Do not persist final REQUIREMENTS content until explicit confirmation. Never rationalize past it.
 
 ---