gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -1481,6 +1481,13 @@ async function configureAdvanced(ctx, prefs) {
     const tokenCost = await promptBoolean(ctx, "Show token cost in footer", prefs.show_token_cost, false);
     if (tokenCost !== undefined)
         prefs.show_token_cost = tokenCost;
+    const minRequestInterval = await promptInteger(ctx, "Minimum interval between auto-mode LLM requests (ms, 0 to disable)", prefs.min_request_interval_ms, "0");
+    if (minRequestInterval === "clear") {
+        delete prefs.min_request_interval_ms;
+    }
+    else if (minRequestInterval !== undefined) {
+        prefs.min_request_interval_ms = minRequestInterval;
+    }
     const widget = await promptEnum(ctx, "Auto-mode widget display", prefs.widget_mode, ["full", "small", "min", "off"], "full");
     if (widget !== undefined)
         prefs.widget_mode = widget;
@@ -1668,8 +1675,10 @@ export function serializePreferencesToFrontmatter(prefs) {
         "budget_ceiling", "budget_enforcement", "context_pause_threshold",
         "notifications", "cmux", "remote_questions", "git",
         "stale_commit_threshold_minutes",
+        "min_request_interval_ms",
         "post_unit_hooks", "pre_dispatch_hooks",
-        "dynamic_routing", "uok", "token_profile", "service_tier", "flat_rate_providers",
+        "dynamic_routing", "disabled_model_providers", "uok", "token_profile",
+        "service_tier", "flat_rate_providers",
         "phases", "parallel", "slice_parallel",
         "reactive_execution", "gate_evaluation",
         "auto_visualize", "auto_report",

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

@@ -6,11 +6,13 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { deriveState } from "./state.js";
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile } from "./paths.js";
 import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bridge.js";
 import { formatDuration } from "../shared/format-utils.js";
+import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -68,6 +70,48 @@ function collectSliceSummaries(basePath, milestoneId) {
     }
     return summaries;
 }
+/**
+ * Inspect a single slice's EVAL-REVIEW.md without throwing.
+ *
+ * One async file read attempt — no `existsSync` precheck (defense against the
+ * TOCTOU race that bit prior implementations). ENOENT is treated as `absent`.
+ * Other read errors
+ * propagate so callers can decide how to handle them; the {@link handleShip}
+ * caller wraps them in a non-blocking warning rather than aborting the
+ * ship.
+ *
+ * @param basePath - project root.
+ * @param milestoneId - active milestone ID.
+ * @param sliceId - slice ID to check.
+ * @returns A {@link SliceEvalCheck} discriminating on the four valid states.
+ * @throws Forwarded `readFile` errors other than `ENOENT`.
+ */
+export async function checkSliceEvalReview(basePath, milestoneId, sliceId) {
+    const path = resolveSliceFile(basePath, milestoneId, sliceId, "EVAL-REVIEW");
+    if (!path) {
+        return { sliceId, kind: "absent" };
+    }
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { sliceId, kind: "absent" };
+        }
+        throw err;
+    }
+    const parsed = parseEvalReviewFrontmatter(raw);
+    if (!parsed.ok) {
+        return { sliceId, kind: "malformed", error: parsed.error, pointer: parsed.pointer };
+    }
+    return {
+        sliceId,
+        kind: "ok",
+        verdict: parsed.data.verdict,
+        overall_score: parsed.data.overall_score,
+    };
+}
 function generatePRContent(basePath, milestoneId, milestoneTitle) {
     const title = `feat: ${milestoneTitle || milestoneId}`;
     const sections = [];
@@ -154,6 +198,27 @@ export async function handleShip(args, ctx, _pi) {
         ctx.ui.notify(`Milestone ${milestoneId} may not be complete (phase: ${state.phase}). Use --force to ship anyway.`, "warning");
         return;
     }
+    // 2b. Pre-ship soft warning on EVAL-REVIEW.md status (non-blocking).
+    for (const sliceId of listSliceIds(basePath, milestoneId)) {
+        let result;
+        try {
+            result = await checkSliceEvalReview(basePath, milestoneId, sliceId);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Could not read EVAL-REVIEW.md for ${sliceId}: ${msg}`, "warning");
+            continue;
+        }
+        if (result.kind === "absent") {
+            ctx.ui.notify(`Slice ${sliceId} has no EVAL-REVIEW.md — consider /gsd eval-review ${sliceId} (non-blocking).`, "warning");
+        }
+        else if (result.kind === "malformed") {
+            ctx.ui.notify(`Slice ${sliceId} EVAL-REVIEW.md frontmatter invalid at ${result.pointer}: ${result.error} (non-blocking).`, "warning");
+        }
+        else if (result.verdict === "NOT_IMPLEMENTED") {
+            ctx.ui.notify(`Slice ${sliceId} eval verdict NOT_IMPLEMENTED (overall ${result.overall_score}/100) — shipping anyway, but the eval gap is unresolved.`, "warning");
+        }
+    }
     // 3. Generate PR content
     const { title, body } = generatePRContent(basePath, milestoneId, milestoneTitle);
     // 4. Dry-run — just show the PR content

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

@@ -0,0 +1,309 @@
+// GSD-2 — In-TUI handler for /gsd worktree commands (list, merge, clean, remove).
+//
+// Mirrors the CLI subcommands in src/worktree-cli.ts but emits results via
+// ctx.ui.notify() instead of writing colored output to stderr. Reuses the
+// same extension modules (worktree-manager, native-git-bridge, etc.) so the
+// behavior is identical to the CLI surface.
+import { existsSync } from "node:fs";
+import { projectRoot } from "./commands/context.js";
+import { listWorktrees, removeWorktree, mergeWorktreeToMain, diffWorktreeAll, diffWorktreeNumstat, worktreeBranchName, } from "./worktree-manager.js";
+import { nativeHasChanges, nativeDetectMainBranch, nativeCommitCountBetween, } from "./native-git-bridge.js";
+import { inferCommitType } from "./git-service.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+// ─── Status helper ─────────────────────────────────────────────────────────
+function getStatus(basePath, name, wtPath) {
+    const diff = diffWorktreeAll(basePath, name);
+    const numstat = diffWorktreeNumstat(basePath, name);
+    const filesChanged = diff.added.length + diff.modified.length + diff.removed.length;
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    for (const s of numstat) {
+        linesAdded += s.added;
+        linesRemoved += s.removed;
+    }
+    let uncommitted = false;
+    try {
+        uncommitted = existsSync(wtPath) && nativeHasChanges(wtPath);
+    }
+    catch {
+        // native check failure → treat as clean for display purposes
+    }
+    let commits = 0;
+    try {
+        const main = nativeDetectMainBranch(basePath);
+        commits = nativeCommitCountBetween(basePath, main, worktreeBranchName(name));
+    }
+    catch {
+        // commit count unavailable → leave at 0
+    }
+    return {
+        name,
+        path: wtPath,
+        branch: worktreeBranchName(name),
+        exists: existsSync(wtPath),
+        filesChanged,
+        linesAdded,
+        linesRemoved,
+        uncommitted,
+        commits,
+    };
+}
+// ─── Formatters (exported for tests) ────────────────────────────────────────
+export function formatWorktreeList(statuses) {
+    if (statuses.length === 0) {
+        return "No worktrees.\n\nCreate one from the CLI: gsd -w <name>";
+    }
+    const lines = [`Worktrees — ${statuses.length}`, ""];
+    for (const s of statuses) {
+        const badge = s.uncommitted
+            ? "(uncommitted)"
+            : s.filesChanged > 0
+                ? "(unmerged)"
+                : "(clean)";
+        lines.push(`  ${s.name} ${badge}`);
+        lines.push(`    branch  ${s.branch}`);
+        lines.push(`    path    ${s.path}`);
+        if (s.filesChanged > 0) {
+            lines.push(`    diff    ${s.filesChanged} file${s.filesChanged === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved}, ${s.commits} commit${s.commits === 1 ? "" : "s"}`);
+        }
+        lines.push("");
+    }
+    lines.push("Commands:");
+    lines.push("  /gsd worktree merge <name>   Merge into main and clean up");
+    lines.push("  /gsd worktree remove <name>  Remove a worktree (--force to skip safety checks)");
+    lines.push("  /gsd worktree clean          Remove all merged/empty worktrees");
+    return lines.join("\n");
+}
+export function formatCleanKeepReason(status) {
+    if (!status.exists) {
+        return "directory missing — run 'git worktree prune' to unregister";
+    }
+    if (status.filesChanged > 0) {
+        return `${status.filesChanged} changed file${status.filesChanged === 1 ? "" : "s"}${status.uncommitted ? ", uncommitted" : ""}`;
+    }
+    return "uncommitted changes";
+}
+// ─── Subcommand: list ───────────────────────────────────────────────────────
+async function handleList(ctx) {
+    const basePath = projectRoot();
+    const worktrees = listWorktrees(basePath);
+    const statuses = worktrees.map((wt) => getStatus(basePath, wt.name, wt.path));
+    ctx.ui.notify(formatWorktreeList(statuses), "info");
+}
+// ─── Subcommand: merge ──────────────────────────────────────────────────────
+async function handleMerge(args, ctx) {
+    const basePath = projectRoot();
+    const worktrees = listWorktrees(basePath);
+    const trimmed = args.trim();
+    let target = trimmed;
+    if (!target) {
+        if (worktrees.length === 1) {
+            target = worktrees[0].name;
+        }
+        else if (worktrees.length === 0) {
+            ctx.ui.notify("No worktrees to merge.", "info");
+            return;
+        }
+        else {
+            const names = worktrees.map((w) => w.name).join(", ");
+            ctx.ui.notify(`Usage: /gsd worktree merge <name>\n\nWorktrees: ${names}`, "warning");
+            return;
+        }
+    }
+    const wt = worktrees.find((w) => w.name === target);
+    if (!wt) {
+        const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+        ctx.ui.notify(`Worktree "${target}" not found.\n\nAvailable: ${available}`, "error");
+        return;
+    }
+    const status = getStatus(basePath, target, wt.path);
+    if (status.filesChanged === 0 && !status.uncommitted) {
+        try {
+            removeWorktree(basePath, target, { deleteBranch: true });
+            ctx.ui.notify(`Removed empty worktree ${target}.`, "info");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`, "error");
+        }
+        return;
+    }
+    if (status.uncommitted) {
+        try {
+            autoCommitCurrentBranch(wt.path, "worktree-merge", target);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify([
+                `Auto-commit before merge failed: ${msg}`,
+                "",
+                `Commit or stash changes in ${wt.path}, then re-run /gsd worktree merge ${target}.`,
+            ].join("\n"), "error");
+            return;
+        }
+    }
+    const commitType = inferCommitType(target);
+    const mainBranch = nativeDetectMainBranch(basePath);
+    const commitMessage = `${commitType}: merge worktree ${target}\n\nGSD-Worktree: ${target}`;
+    try {
+        mergeWorktreeToMain(basePath, target, commitMessage);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (err instanceof GSDError && err.code === GSD_GIT_ERROR) {
+            ctx.ui.notify(`Merge requires the main branch to be checked out: ${msg}\n\nSwitch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then re-run /gsd worktree merge ${target}.`, "error");
+        }
+        else {
+            ctx.ui.notify(`Merge failed: ${msg}\n\nResolve conflicts manually, then run /gsd worktree merge ${target} again.`, "error");
+        }
+        return;
+    }
+    const successLines = [
+        `Merged ${target} → ${mainBranch}`,
+        `  ${status.filesChanged} file${status.filesChanged === 1 ? "" : "s"}, +${status.linesAdded} -${status.linesRemoved}`,
+        `  commit: ${commitMessage.split("\n")[0]}`,
+    ];
+    try {
+        removeWorktree(basePath, target, { deleteBranch: true });
+        ctx.ui.notify(successLines.join("\n"), "info");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const cleanupLines = [
+            ...successLines,
+            "",
+            `Cleanup failed after the merge succeeded: ${msg}`,
+            err instanceof GSDError && err.code === GSD_GIT_ERROR
+                ? `Switch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then remove the worktree manually with /gsd worktree remove ${target} --force.`
+                : `Remove the worktree manually with /gsd worktree remove ${target} --force, or run 'git worktree prune' to clean up dangling registrations.`,
+        ];
+        ctx.ui.notify(cleanupLines.join("\n"), "warning");
+    }
+}
+// ─── Subcommand: clean ──────────────────────────────────────────────────────
+async function handleClean(ctx) {
+    const basePath = projectRoot();
+    const worktrees = listWorktrees(basePath);
+    if (worktrees.length === 0) {
+        ctx.ui.notify("No worktrees to clean.", "info");
+        return;
+    }
+    const removed = [];
+    const kept = [];
+    for (const wt of worktrees) {
+        const status = getStatus(basePath, wt.name, wt.path);
+        if (status.filesChanged === 0 && !status.uncommitted) {
+            try {
+                removeWorktree(basePath, wt.name, { deleteBranch: true });
+                removed.push(wt.name);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                kept.push(`${wt.name} (failed: ${msg})`);
+            }
+        }
+        else {
+            const reason = formatCleanKeepReason(status);
+            kept.push(`${wt.name} (${reason})`);
+        }
+    }
+    const lines = [`Cleaned ${removed.length} worktree${removed.length === 1 ? "" : "s"}.`];
+    if (removed.length > 0) {
+        lines.push("", "Removed:");
+        for (const n of removed)
+            lines.push(`  ✓ ${n}`);
+    }
+    if (kept.length > 0) {
+        lines.push("", "Kept:");
+        for (const n of kept)
+            lines.push(`  ─ ${n}`);
+    }
+    ctx.ui.notify(lines.join("\n"), "info");
+}
+// ─── Subcommand: remove ─────────────────────────────────────────────────────
+async function handleRemove(args, ctx) {
+    const basePath = projectRoot();
+    const tokens = args.trim().split(/\s+/).filter(Boolean);
+    const force = tokens.includes("--force");
+    const name = tokens.find((t) => t !== "--force");
+    if (!name) {
+        ctx.ui.notify("Usage: /gsd worktree remove <name> [--force]", "warning");
+        return;
+    }
+    const worktrees = listWorktrees(basePath);
+    const wt = worktrees.find((w) => w.name === name);
+    if (!wt) {
+        const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+        ctx.ui.notify(`Worktree "${name}" not found.\n\nAvailable: ${available}`, "error");
+        return;
+    }
+    const status = getStatus(basePath, name, wt.path);
+    if ((status.filesChanged > 0 || status.uncommitted) && !force) {
+        ctx.ui.notify([
+            `Worktree "${name}" has pending changes (${formatCleanKeepReason(status)}).`,
+            "",
+            `  Merge first:     /gsd worktree merge ${name}`,
+            `  Or force-remove: /gsd worktree remove ${name} --force`,
+        ].join("\n"), "warning");
+        return;
+    }
+    try {
+        removeWorktree(basePath, name, { deleteBranch: true });
+        ctx.ui.notify(`Removed worktree ${name}.`, "info");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`, "error");
+    }
+}
+// ─── Help text ──────────────────────────────────────────────────────────────
+const HELP_TEXT = [
+    "Usage: /gsd worktree <command> [args]",
+    "",
+    "Commands:",
+    "  list                       Show all worktrees with status",
+    "  merge [name]               Merge a worktree into main, then remove it",
+    "  remove <name> [--force]    Remove a worktree (refuses unmerged changes without --force)",
+    "  clean                      Remove all merged/empty worktrees",
+    "",
+    "The -w flag (CLI only) creates/resumes worktrees on session start:",
+    "  gsd -w               Auto-name a new worktree, or resume the only active one",
+    "  gsd -w my-feature    Create or resume a named worktree",
+].join("\n");
+// ─── Dispatcher ─────────────────────────────────────────────────────────────
+export async function handleWorktree(args, ctx) {
+    const trimmed = args.trim();
+    const lowered = trimmed.toLowerCase();
+    if (!lowered || lowered === "help" || lowered === "--help" || lowered === "-h") {
+        ctx.ui.notify(HELP_TEXT, "info");
+        return;
+    }
+    try {
+        if (lowered === "list" || lowered === "ls") {
+            await handleList(ctx);
+            return;
+        }
+        if (lowered === "merge" || lowered.startsWith("merge ")) {
+            await handleMerge(trimmed.replace(/^merge\s*/i, ""), ctx);
+            return;
+        }
+        if (lowered === "clean") {
+            await handleClean(ctx);
+            return;
+        }
+        if (lowered === "remove" ||
+            lowered.startsWith("remove ") ||
+            lowered === "rm" ||
+            lowered.startsWith("rm ")) {
+            const stripped = trimmed.replace(/^(remove|rm)\s*/i, "");
+            await handleRemove(stripped, ctx);
+            return;
+        }
+        ctx.ui.notify(`Unknown worktree command: ${trimmed}\n\n${HELP_TEXT}`, "warning");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Worktree command failed: ${msg}`, "error");
+    }
+}

package/dist/resources/extensions/gsd/context-budget.js

@@ -21,6 +21,8 @@ const VERIFICATION_RATIO = 0.10;
 const CHARS_PER_TOKEN = 4;
 /** Default context window when none can be resolved (D002) */
 const DEFAULT_CONTEXT_WINDOW = 200_000;
+/** Conservative effective context for Claude Code subscription routing (#4676) */
+const CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW = 200_000;
 /** Percentage of context consumed before suggesting a continue-here checkpoint */
 const CONTINUE_THRESHOLD_PERCENT = 70;
 // ─── Task count bounds ───────────────────────────────────────────────────────
@@ -109,7 +111,7 @@ export function truncateAtSectionBoundary(content, budgetChars) {
  *
  * Supports "provider/model" format in preferences for explicit provider targeting.
  */
-export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow) {
+export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow, sessionProvider) {
     // Step 1: Try configured executor model
     if (preferences?.models?.execution && registry) {
         const executionConfig = preferences.models.execution;
@@ -119,13 +121,13 @@ export function resolveExecutorContextWindow(registry, preferences, sessionConte
         if (modelId) {
             const model = findModelById(registry, modelId);
             if (model && model.contextWindow > 0) {
-                return model.contextWindow;
+                return resolveEffectiveContextWindow(model.contextWindow, model.provider);
             }
         }
     }
     // Step 2: Fall back to session context window
     if (sessionContextWindow && sessionContextWindow > 0) {
-        return sessionContextWindow;
+        return resolveEffectiveContextWindow(sessionContextWindow, sessionProvider);
     }
     // Step 3: Fall back to default (D002)
     return DEFAULT_CONTEXT_WINDOW;
@@ -151,6 +153,12 @@ function resolveTaskCountMax(contextWindow) {
     }
     return 3; // fallback — unreachable given tiers include 0
 }
+function resolveEffectiveContextWindow(contextWindow, provider) {
+    if (provider?.toLowerCase() === "claude-code" && contextWindow > CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW) {
+        return CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW;
+    }
+    return contextWindow;
+}
 /**
  * Split content into sections at `### ` headings or `---` dividers.
  * Each section includes its leading marker.

package/dist/resources/extensions/gsd/dashboard-overlay.js

@@ -14,7 +14,7 @@ import { resolveMilestoneFile } from "./paths.js";
 import { getAutoDashboardData } from "./auto.js";
 import { getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice, aggregateByModel, aggregateCacheHitRate, formatCost, formatTokenCount, formatCostProjection, } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { getActiveWorktreeName } from "./worktree-command.js";
+import { getActiveWorktreeName } from "./worktree-session-state.js";
 import { getWorkerBatches, hasActiveWorkers } from "../subagent/worker-registry.js";
 import { formatDuration, padRight, joinColumns, centerLine, fitColumns, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
 import { estimateTimeRemaining } from "./auto-dashboard.js";

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

@@ -108,9 +108,9 @@ const STATUS_SECTION_MAP = [
 /**
  * Generate full REQUIREMENTS.md content from an array of Requirement objects.
  * Groups requirements by status into sections (## Active, ## Validated, etc.),
- * each containing ### RXXX — Description headings with bullet fields.
- * Only emits sections that have content. Appends Traceability table and
- * Coverage Summary at the bottom.
+ * each containing ### RXXX — Description headings with bullet fields. Empty
+ * status sections are emitted too because the deep-mode validator treats their
+ * presence as part of the canonical contract.
  */
 export function generateRequirementsMd(requirements) {
     const lines = [];
@@ -129,11 +129,9 @@ export function generateRequirementsMd(requirements) {
     // Emit sections in canonical order
     for (const { status, heading } of STATUS_SECTION_MAP) {
         const reqs = byStatus.get(status);
-        if (!reqs || reqs.length === 0)
-            continue;
         lines.push(`## ${heading}`);
         lines.push('');
-        for (const r of reqs) {
+        for (const r of reqs ?? []) {
             lines.push(`### ${r.id} — ${r.description || 'Untitled'}`);
             // Emit bullet fields — only those with content
             if (r.class)
@@ -179,6 +177,12 @@ export function generateRequirementsMd(requirements) {
     lines.push(`- Unmapped active requirements: 0`);
     return lines.join('\n') + '\n';
 }
+function isRootCanonicalArtifact(opts) {
+    if (opts.milestone_id || opts.slice_id || opts.task_id)
+        return false;
+    return (opts.artifact_type === 'PROJECT' ||
+        opts.artifact_type === 'REQUIREMENTS');
+}
 // ─── Next Decision ID ─────────────────────────────────────────────────────
 /**
  * Compute the next decision ID from the current DB state.
@@ -257,34 +261,61 @@ export async function saveRequirementToDb(fields, basePath) {
     try {
         const db = await import('./gsd-db.js');
         // Atomic ID assignment + insert inside a transaction.
-        const id = db.transaction(() => {
+        const txResult = db.transaction(() => {
             const adapter = db._getAdapter();
             if (!adapter)
                 throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+            const existingRow = adapter
+                .prepare(`SELECT * FROM requirements
+           WHERE LOWER(TRIM(description)) = LOWER(TRIM(:description))
+             AND LOWER(COALESCE(status, 'active')) = 'active'
+             AND superseded_by IS NULL
+           ORDER BY id
+           LIMIT 1`)
+                .get({ ':description': fields.description });
+            const previousRow = existingRow
+                ? {
+                    id: existingRow['id'],
+                    class: existingRow['class'],
+                    status: existingRow['status'],
+                    description: existingRow['description'],
+                    why: existingRow['why'],
+                    source: existingRow['source'],
+                    primary_owner: existingRow['primary_owner'],
+                    supporting_slices: existingRow['supporting_slices'],
+                    validation: existingRow['validation'],
+                    notes: existingRow['notes'],
+                    full_content: existingRow['full_content'],
+                    superseded_by: existingRow['superseded_by'] ?? null,
+                }
+                : null;
             const row = adapter
                 .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
                 .get();
             const maxNum = row ? row['max_num'] : null;
-            const nextId = (maxNum == null || isNaN(maxNum))
-                ? 'R001'
-                : `R${String(maxNum + 1).padStart(3, '0')}`;
+            const nextId = existingRow
+                ? String(existingRow['id'])
+                : (maxNum == null || isNaN(maxNum))
+                    ? 'R001'
+                    : `R${String(maxNum + 1).padStart(3, '0')}`;
             const requirement = {
                 id: nextId,
-                class: fields.class,
-                status: fields.status ?? 'active',
+                class: fields.class || existingRow?.['class'] || '',
+                status: fields.status ?? existingRow?.['status'] ?? 'active',
                 description: fields.description,
                 why: fields.why,
                 source: fields.source,
-                primary_owner: fields.primary_owner ?? '',
-                supporting_slices: fields.supporting_slices ?? '',
-                validation: fields.validation ?? '',
-                notes: fields.notes ?? '',
-                full_content: '',
-                superseded_by: null,
+                primary_owner: fields.primary_owner ?? existingRow?.['primary_owner'] ?? '',
+                supporting_slices: fields.supporting_slices ?? existingRow?.['supporting_slices'] ?? '',
+                validation: fields.validation ?? existingRow?.['validation'] ?? '',
+                notes: fields.notes ?? existingRow?.['notes'] ?? '',
+                full_content: existingRow?.['full_content'] ?? '',
+                superseded_by: existingRow?.['superseded_by'] ?? null,
             };
             db.upsertRequirement(requirement);
-            return nextId;
+            return { id: nextId, isNew: !existingRow, previousRow };
         });
+        const { id, isNew, previousRow } = txResult;
         // Fetch all requirements for full file regeneration
         const adapter = db._getAdapter();
         let allRequirements = [];
@@ -314,7 +345,12 @@ export async function saveRequirementToDb(fields, basePath) {
         catch (diskErr) {
             logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String(diskErr.message) });
             try {
-                db.deleteRequirementById(id);
+                if (isNew) {
+                    db.deleteRequirementById(id);
+                }
+                else if (previousRow) {
+                    db.upsertRequirement(previousRow);
+                }
             }
             catch (rollbackErr) {
                 logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String(rollbackErr.message) });
@@ -657,14 +693,25 @@ export async function saveArtifactToDb(opts, basePath) {
         if (!fullPath.startsWith(gsdDir)) {
             throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
         }
+        let contentToPersist = opts.content;
+        if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
+            const activeRequirements = db.getActiveRequirements();
+            if (activeRequirements.length === 0) {
+                throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDb: REQUIREMENTS final save requires active DB-backed requirements');
+            }
+            contentToPersist = generateRequirementsMd(activeRequirements);
+        }
         // Shrinkage guard: if the file already exists and the new content is
         // significantly smaller (<50%), preserve the richer file on disk and
-        // store its content in the DB instead of the abbreviated version.
-        let dbContent = opts.content;
+        // store its content in the DB instead of the abbreviated version. Root
+        // canonical artifacts are exempt because their content is rendered from
+        // canonical DB state, and cleanup/consolidation is often intentionally much
+        // smaller than a malformed accumulated file.
+        let dbContent = contentToPersist;
         let skipDiskWrite = false;
-        if (existsSync(fullPath)) {
+        if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
             const existingSize = statSync(fullPath).size;
-            const newSize = Buffer.byteLength(opts.content, 'utf-8');
+            const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
             if (existingSize > 0 && newSize < existingSize * 0.5) {
                 logWarning('manifest', `new content (${newSize}B) is <50% of existing file (${existingSize}B), preserving disk file`, { fn: 'saveArtifactToDb', path: opts.path });
                 dbContent = readFileSync(fullPath, 'utf-8');
@@ -682,7 +729,7 @@ export async function saveArtifactToDb(opts, basePath) {
         // Write the file to disk (only if we're not preserving a richer existing file)
         if (!skipDiskWrite) {
             try {
-                await saveFile(fullPath, opts.content);
+                await saveFile(fullPath, contentToPersist);
             }
             catch (diskErr) {
                 logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String(diskErr.message) });