gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2ff77b0ce

package/src/resources/extensions/gsd/commands-extensions.ts

@@ -12,6 +12,7 @@ import { dirname, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { lockSync, unlockSync } from "proper-lockfile";
+import { gsdHome } from "./gsd-home.js";
 
 /**
  * Strict numeric comparison of two npm-style version strings.
@@ -54,7 +55,6 @@ export function isVersionGreater(a: string, b: string): boolean {
   return false;
 }
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 // ─── Types (mirrored from extension-registry.ts) ────────────────────────────
 
@@ -96,11 +96,11 @@ interface ExtensionRegistry {
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 
 function getRegistryPath(): string {
-  return join(gsdHome, "extensions", "registry.json");
+  return join(gsdHome(), "extensions", "registry.json");
 }
 
 function getAgentExtensionsDir(): string {
-  return join(gsdHome, "agent", "extensions");
+  return join(gsdHome(), "agent", "extensions");
 }
 
 function loadRegistry(): ExtensionRegistry {
@@ -251,7 +251,7 @@ function discoverManifests(): Map<string, ExtensionManifest> {
 }
 
 function getInstalledExtDir(): string {
-  return join(gsdHome, "extensions");
+  return join(gsdHome(), "extensions");
 }
 
 // Source: derived from npm/git URL conventions (from RESEARCH.md)

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -11,7 +11,7 @@ import { join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
-import { getHomeDir } from "./home-dir.js";
+import { gsdHome } from "./gsd-home.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
 import {
@@ -24,7 +24,7 @@ import {
 } from "./doctor.js";
 import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
@@ -69,7 +69,7 @@ async function fetchLatestVersionForCommand(): Promise<string | null> {
 }
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
     doctorSummary: reportText,
@@ -203,7 +203,7 @@ export async function handleCapture(args: string, ctx: ExtensionCommandContext):
     return;
   }
 
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
 
   // Ensure .gsd/ exists — capture should work even without a milestone
   const gsdDir = gsdRoot(basePath);
@@ -256,7 +256,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
     roadmapContext: roadmapContext || "(no active roadmap)",
   });
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(
@@ -270,7 +270,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
 }
 
 export async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const state = await deriveState(basePath);
   const mid = state.activeMilestone?.id ?? "none";
   const sid = state.activeSlice?.id ?? "none";
@@ -343,7 +343,7 @@ export async function handleKnowledge(args: string, ctx: ExtensionCommandContext
   }
 
   const type = typeArg as "rule" | "pattern" | "lesson";
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const state = await deriveState(basePath);
   const scope = state.activeMilestone?.id
     ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
@@ -372,7 +372,7 @@ Examples:
   }
 
   const [hookName, unitType, unitId] = parts;
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
 
   // Import the hook trigger function
   const { triggerHookManually, formatHookStatus, getHookStatus } = await import("./post-unit-hooks.js");

package/src/resources/extensions/gsd/commands-logs.ts

@@ -15,6 +15,7 @@ import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "nod
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { loadJsonFileOrNull } from "./json-persistence.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -243,7 +244,7 @@ function summarizeDebugLog(filePath: string): {
 // ─── Main Handler ───────────────────────────────────────────────────────────
 
 export async function handleLogs(args: string, ctx: ExtensionCommandContext): Promise<void> {
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const parts = args.trim().split(/\s+/).filter(Boolean);
   const subCmd = parts[0] ?? "";
 

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -13,10 +13,10 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js";
+import { gsdHome } from "./gsd-home.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -70,7 +70,7 @@ function readMcpConfigs(): McpServerRawConfig[] {
   const configPaths = [
     join(process.cwd(), ".mcp.json"),
     join(process.cwd(), ".gsd", "mcp.json"),
-    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
+    join(gsdHome(), "mcp.json"),
   ];
 
   for (const configPath of configPaths) {

package/src/resources/extensions/gsd/commands-scan.ts

@@ -20,6 +20,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
 
 import { loadPrompt } from "./prompt-loader.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -86,7 +87,7 @@ export async function handleScan(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
 ): Promise<void> {
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const { focus } = parseScanArgs(args);
   const outputDir = join(basePath, ".gsd", "codebase");
   const outputPaths = buildScanOutputPaths(focus, basePath);

package/src/resources/extensions/gsd/commands-ship.ts

@@ -9,12 +9,15 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 
 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, type Verdict } from "./eval-review-schema.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -76,6 +79,75 @@ function collectSliceSummaries(basePath: string, milestoneId: string): string[]
   return summaries;
 }
 
+/**
+ * Discriminated result of inspecting a slice's `<sliceId>-EVAL-REVIEW.md`
+ * for the pre-ship soft warning. Pure data — the caller decides how to
+ * surface each variant to the user.
+ */
+export type SliceEvalCheck =
+  | { readonly sliceId: string; readonly kind: "absent" }
+  | {
+      readonly sliceId: string;
+      readonly kind: "malformed";
+      readonly error: string;
+      readonly pointer: string;
+    }
+  | {
+      readonly sliceId: string;
+      readonly kind: "ok";
+      readonly verdict: Verdict;
+      readonly overall_score: number;
+    };
+
+/**
+ * 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: string,
+  milestoneId: string,
+  sliceId: string,
+): Promise<SliceEvalCheck> {
+  const path = resolveSliceFile(basePath, milestoneId, sliceId, "EVAL-REVIEW");
+  if (!path) {
+    return { sliceId, kind: "absent" };
+  }
+
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).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: string, milestoneId: string, milestoneTitle: string): PRContent {
   const title = `feat: ${milestoneTitle || milestoneId}`;
 
@@ -151,7 +223,7 @@ export async function handleShip(
   ctx: ExtensionCommandContext,
   _pi: ExtensionAPI,
 ): Promise<void> {
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const dryRun = args.includes("--dry-run");
   const draft = args.includes("--draft");
   const force = args.includes("--force");
@@ -182,6 +254,34 @@ export async function handleShip(
     return;
   }
 
+  // 2b. Pre-ship soft warning on EVAL-REVIEW.md status (non-blocking).
+  for (const sliceId of listSliceIds(basePath, milestoneId)) {
+    let result: SliceEvalCheck;
+    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);
 

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -23,6 +23,7 @@ import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin, type WorkflowPlugin } from "./workflow-plugins.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -196,7 +197,7 @@ export async function handleStart(
   // ─── Resume detection ───────────────────────────────────────────────────
   // /gsd start --resume or /gsd start resume → resume in-progress workflow
   if (trimmed === "--resume" || trimmed === "resume") {
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const inProgress = findInProgressWorkflows(basePath);
     if (inProgress.length === 0) {
       ctx.ui.notify("No in-progress workflows found.", "info");
@@ -247,7 +248,7 @@ export async function handleStart(
 
   // Show in-progress workflows when /gsd start is called with no args
   if (!trimmed) {
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const inProgress = findInProgressWorkflows(basePath);
     if (inProgress.length > 0) {
       const wf = inProgress[0];
@@ -346,7 +347,7 @@ export async function handleStart(
 
   const templateId = match.id;
   const template = match.template;
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const date = new Date().toISOString().split("T")[0];
 
   // Load the workflow template content — prefer a project/global plugin
@@ -581,7 +582,7 @@ export function dispatchMarkdownPhasePlugin(
   }
 
   const templateId = plugin.name;
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const date = new Date().toISOString().split("T")[0];
   let workflowContent: string;
   try {

package/src/resources/extensions/gsd/context-budget.ts

@@ -29,6 +29,9 @@ 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;
 
@@ -175,6 +178,7 @@ export function resolveExecutorContextWindow(
   registry: MinimalModelRegistry | undefined,
   preferences: MinimalPreferences | undefined,
   sessionContextWindow?: number,
+  sessionProvider?: string,
 ): number {
   // Step 1: Try configured executor model
   if (preferences?.models?.execution && registry) {
@@ -186,14 +190,14 @@ export function resolveExecutorContextWindow(
     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)
@@ -223,6 +227,13 @@ function resolveTaskCountMax(contextWindow: number): number {
   return 3; // fallback — unreachable given tiers include 0
 }
 
+function resolveEffectiveContextWindow(contextWindow: number, provider?: string): number {
+  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/src/resources/extensions/gsd/db-writer.ts

@@ -124,9 +124,9 @@ const STATUS_SECTION_MAP: Array<{ status: string; heading: string }> = [
 /**
  * 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: Requirement[]): string {
   const lines: string[] = [];
@@ -147,12 +147,10 @@ export function generateRequirementsMd(requirements: Requirement[]): string {
   // 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
@@ -199,6 +197,14 @@ export function generateRequirementsMd(requirements: Requirement[]): string {
   return lines.join('\n') + '\n';
 }
 
+function isRootCanonicalArtifact(opts: SaveArtifactOpts): boolean {
+  if (opts.milestone_id || opts.slice_id || opts.task_id) return false;
+  return (
+    opts.artifact_type === 'PROJECT' ||
+    opts.artifact_type === 'REQUIREMENTS'
+  );
+}
+
 // ─── Next Decision ID ─────────────────────────────────────────────────────
 
 /**
@@ -298,36 +304,49 @@ export async function saveRequirementToDb(
     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 row = adapter
         .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
         .get();
       const maxNum = row ? (row['max_num'] as number | null) : null;
-      const nextId = (maxNum == null || isNaN(maxNum))
+      const nextId = existingRow
+        ? String(existingRow['id'])
+        : (maxNum == null || isNaN(maxNum))
         ? 'R001'
         : `R${String(maxNum + 1).padStart(3, '0')}`;
 
       const requirement: Requirement = {
         id: nextId,
-        class: fields.class,
-        status: fields.status ?? 'active',
+        class: fields.class || (existingRow?.['class'] as string | undefined) || '',
+        status: fields.status ?? (existingRow?.['status'] as string | undefined) ?? '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'] as string | undefined) ?? '',
+        supporting_slices: fields.supporting_slices ?? (existingRow?.['supporting_slices'] as string | undefined) ?? '',
+        validation: fields.validation ?? (existingRow?.['validation'] as string | undefined) ?? '',
+        notes: fields.notes ?? (existingRow?.['notes'] as string | undefined) ?? '',
+        full_content: (existingRow?.['full_content'] as string | undefined) ?? '',
+        superseded_by: (existingRow?.['superseded_by'] as string | null | undefined) ?? null,
       };
 
       db.upsertRequirement(requirement);
-      return nextId;
+      return { id: nextId };
     });
+    const { id } = txResult;
 
     // Fetch all requirements for full file regeneration
     const adapter = db._getAdapter();
@@ -356,13 +375,7 @@ export async function saveRequirementToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String((diskErr as Error).message) });
-      try {
-        db.deleteRequirementById(id);
-      } catch (rollbackErr) {
-        logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String((rollbackErr as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement remains committed', { fn: 'saveRequirementToDb', id, error: String((diskErr as Error).message) });
     }
     invalidateStateCache();
     clearPathCache();
@@ -498,13 +511,7 @@ export async function saveDecisionToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).message) });
-      try {
-        db.deleteDecisionById(id);
-      } catch (rollbackErr) {
-        logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveDecisionToDb', id, error: String((rollbackErr as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'DECISIONS.md projection write failed; DB decision remains committed', { fn: 'saveDecisionToDb', id, error: String((diskErr as Error).message) });
     }
     // #2661: When a decision defers a slice, update the slice status in the DB
     // so the dispatcher skips it. Without this, STATE.md and DECISIONS.md are
@@ -532,8 +539,8 @@ export async function saveDecisionToDb(
     // ADR-013 dual-write: keep the memory store in sync with every decision
     // persisted via the legacy gsd_save_decision path. Without this, prompts
     // that still call gsd_save_decision (discuss.md, plan-milestone.md,
-    // guided-plan-slice.md, et al. during the deprecation window) would
-    // create decisions rows invisible to memory_query and loadMemoryBlock.
+    // plan-slice.md, et al.) would create decisions rows invisible to
+    // memory_query and loadMemoryBlock.
     // Best-effort — never throw, never roll back the decision on failure.
     try {
       const { createMemory } = await import('./memory-store.js');
@@ -627,34 +634,7 @@ export async function updateRequirementInDb(
   try {
     const db = await import('./gsd-db.js');
 
-    let existing = db.getRequirementById(id);
-
-    // If requirement doesn't exist in DB, seed the entire requirements table
-    // from REQUIREMENTS.md first (#3346). This handles the standard workflow
-    // where requirements are authored in markdown during discussion but never
-    // imported into the database — making gsd_requirement_update always fail
-    // with "not_found" at milestone completion.
-    if (!existing) {
-      const reqFilePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
-      try {
-        const content = readFileSync(reqFilePath, 'utf-8');
-        const { parseRequirementsSections } = await import('./md-importer.js');
-        const parsed = parseRequirementsSections(content);
-        if (parsed.length > 0) {
-          logWarning('manifest', `Seeding ${parsed.length} requirements from REQUIREMENTS.md into DB (first update triggers import)`, { fn: 'updateRequirementInDb' });
-          for (const req of parsed) {
-            // Only seed if not already in DB (avoid overwriting concurrent inserts)
-            if (!db.getRequirementById(req.id)) {
-              db.upsertRequirement(req);
-            }
-          }
-          // Re-check after seeding
-          existing = db.getRequirementById(id);
-        }
-      } catch {
-        // REQUIREMENTS.md missing or unparseable — fall through to skeleton
-      }
-    }
+    const existing = db.getRequirementById(id);
 
     const base: Requirement = existing ?? {
       id,
@@ -710,11 +690,7 @@ export async function updateRequirementInDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).message) });
-      if (existing) {
-        db.upsertRequirement(existing);
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement update remains committed', { fn: 'updateRequirementInDb', id, error: String((diskErr as Error).message) });
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -756,18 +732,28 @@ export async function saveArtifactToDb(
     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;
+    // Shrinkage guard: if the projection file already exists and the new
+    // content is significantly smaller (<50%), preserve the richer file on
+    // disk, but keep the DB row authoritative with the caller-provided content.
+    // The disk file is a stale projection until the next explicit render.
+    // 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 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');
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDb', path: opts.path });
         skipDiskWrite = true;
       }
     }
@@ -778,17 +764,15 @@ export async function saveArtifactToDb(
       milestone_id: opts.milestone_id ?? null,
       slice_id: opts.slice_id ?? null,
       task_id: opts.task_id ?? null,
-      full_content: dbContent,
+      full_content: contentToPersist,
     });
 
     // 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 as Error).message) });
-        db.deleteArtifactByPath(opts.path);
-        throw diskErr;
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String((diskErr as Error).message) });
       }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.