gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -64,17 +64,12 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
-  let knowledgeBlock = "";
-  const knowledgePath = resolveGsdRootFile(process.cwd(), "KNOWLEDGE");
-  if (existsSync(knowledgePath)) {
-    try {
-      const content = readFileSync(knowledgePath, "utf-8").trim();
-      if (content) {
-        knowledgeBlock = `\n\n[PROJECT KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${content}`;
-      }
-    } catch {
-      // skip
-    }
+  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome, process.cwd());
+  if (globalSizeKb > 4) {
+    ctx.ui.notify(
+      `GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`,
+      "warning",
+    );
   }
 
   let memoryBlock = "";
@@ -126,6 +121,48 @@ export async function buildBeforeAgentStartResult(
   };
 }
 
+export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: string; globalSizeKb: number } {
+  // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
+  let globalKnowledge = "";
+  let globalSizeKb = 0;
+  const globalKnowledgePath = join(gsdHomeDir, "agent", "KNOWLEDGE.md");
+  if (existsSync(globalKnowledgePath)) {
+    try {
+      const content = readFileSync(globalKnowledgePath, "utf-8").trim();
+      if (content) {
+        globalSizeKb = Buffer.byteLength(content, "utf-8") / 1024;
+        globalKnowledge = content;
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific
+  let projectKnowledge = "";
+  const knowledgePath = resolveGsdRootFile(cwd, "KNOWLEDGE");
+  if (existsSync(knowledgePath)) {
+    try {
+      const content = readFileSync(knowledgePath, "utf-8").trim();
+      if (content) projectKnowledge = content;
+    } catch {
+      // skip
+    }
+  }
+
+  if (!globalKnowledge && !projectKnowledge) {
+    return { block: "", globalSizeKb: 0 };
+  }
+
+  const parts: string[] = [];
+  if (globalKnowledge) parts.push(`## Global Knowledge\n\n${globalKnowledge}`);
+  if (projectKnowledge) parts.push(`## Project Knowledge\n\n${projectKnowledge}`);
+  return {
+    block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${parts.join("\n\n")}`,
+    globalSizeKb,
+  };
+}
+
 function buildWorktreeContextBlock(): string {
   const worktreeName = getActiveWorktreeName();
   const worktreeMainCwd = getWorktreeOriginalCwd();

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

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -68,6 +68,8 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "templates", desc: "List available workflow templates" },
   { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
   { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" },
+  { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
+  { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
   { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
 ];
 
@@ -187,6 +189,10 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "flex", desc: "Flex tier (0.5x cost, slower)" },
     { cmd: "status", desc: "Show current service tier setting" },
   ],
+  mcp: [
+    { cmd: "status", desc: "Show all MCP server statuses (default)" },
+    { cmd: "check", desc: "Detailed status for a specific server" },
+  ],
   doctor: [
     { cmd: "fix", desc: "Auto-fix detected issues" },
     { cmd: "heal", desc: "AI-driven deep healing" },

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

@@ -47,15 +47,10 @@ export async function guardRemoteSession(
     return false;
   }
 
-  const unitsMsg = remote.completedUnits != null
-    ? `${remote.completedUnits} units completed`
-    : "";
-
   const choice = await showNextAction(ctx, {
     title: `Auto-mode is running in another terminal (PID ${remote.pid})`,
     summary: [
       `Currently executing: ${unitLabel}`,
-      ...(unitsMsg ? [unitsMsg] : []),
       ...(remote.startedAt ? [`Started: ${remote.startedAt}`] : []),
     ],
     actions: [

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

@@ -36,6 +36,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd triage         Classify and route pending captures",
     "  /gsd skip <unit>    Prevent a unit from auto-mode dispatch",
     "  /gsd undo           Revert last completed unit  [--force]",
+    "  /gsd rethink        Conversational project reorganization — reorder, park, discard, add milestones",
     "  /gsd park [id]      Park a milestone — skip without deleting  [reason]",
     "  /gsd unpark [id]    Reactivate a parked milestone",
     "",
@@ -53,6 +54,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd hooks          Show post-unit hook configuration",
     "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
     "  /gsd fast           Toggle OpenAI service tier  [on|off|flex|status]",
+    "  /gsd mcp            MCP server status and connectivity  [status|check <server>]",
     "",
     "MAINTENANCE",
     "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",

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

@@ -191,10 +191,20 @@ Examples:
     await handleFast(trimmed.replace(/^fast\s*/, "").trim(), ctx);
     return true;
   }
+  if (trimmed === "mcp" || trimmed.startsWith("mcp ")) {
+    const { handleMcpStatus } = await import("../../commands-mcp-status.js");
+    await handleMcpStatus(trimmed.replace(/^mcp\s*/, "").trim(), ctx);
+    return true;
+  }
   if (trimmed === "extensions" || trimmed.startsWith("extensions ")) {
     const { handleExtensions } = await import("../../commands-extensions.js");
     await handleExtensions(trimmed.replace(/^extensions\s*/, "").trim(), ctx);
     return true;
   }
+  if (trimmed === "rethink") {
+    const { handleRethink } = await import("../../rethink.js");
+    await handleRethink(trimmed, ctx, pi);
+    return true;
+  }
   return false;
 }

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

@@ -63,7 +63,7 @@ export async function handleParallelCommand(trimmed: string, _ctx: ExtensionComm
     }
     const lines = ["# Parallel Workers\n"];
     for (const worker of workers) {
-      lines.push(`- **${worker.milestoneId}** (${worker.title}) — ${worker.state} — ${worker.completedUnits} units — $${worker.cost.toFixed(2)}`);
+      lines.push(`- **${worker.milestoneId}** (${worker.title}) — ${worker.state} — $${worker.cost.toFixed(2)}`);
     }
     const state = getOrchestratorState();
     if (state) {

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

@@ -188,6 +188,14 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     return true;
   }
   if (trimmed === "quick" || trimmed.startsWith("quick ")) {
+    if (isAutoActive()) {
+      ctx.ui.notify(
+        "/gsd quick cannot run while auto-mode is active.\n" +
+        "Stop auto-mode first with /gsd stop, then run /gsd quick.",
+        "error",
+      );
+      return true;
+    }
     await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
     return true;
   }

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

@@ -0,0 +1,247 @@
+/**
+ * MCP Status — `/gsd mcp` command handler.
+ *
+ * Shows configured MCP servers, their connection status, and available tools.
+ *
+ * Subcommands:
+ *   /gsd mcp             — Overview of all servers (alias: /gsd mcp status)
+ *   /gsd mcp status      — Same as bare /gsd mcp
+ *   /gsd mcp check <srv> — Detailed status for a specific server
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface McpServerStatus {
+  name: string;
+  transport: "stdio" | "http" | "unknown";
+  connected: boolean;
+  toolCount: number;
+  error: string | undefined;
+}
+
+export interface McpServerDetail extends McpServerStatus {
+  tools: string[];
+}
+
+// ─── Config reader (standalone — does not import mcp-client internals) ──────
+
+interface McpServerRawConfig {
+  name: string;
+  transport: "stdio" | "http" | "unknown";
+  command?: string;
+  args?: string[];
+  url?: string;
+}
+
+function readMcpConfigs(): McpServerRawConfig[] {
+  const servers: McpServerRawConfig[] = [];
+  const seen = new Set<string>();
+  const configPaths = [
+    join(process.cwd(), ".mcp.json"),
+    join(process.cwd(), ".gsd", "mcp.json"),
+  ];
+
+  for (const configPath of configPaths) {
+    try {
+      if (!existsSync(configPath)) continue;
+      const raw = readFileSync(configPath, "utf-8");
+      const data = JSON.parse(raw) as Record<string, unknown>;
+      const mcpServers = (data.mcpServers ?? data.servers) as
+        | Record<string, Record<string, unknown>>
+        | undefined;
+      if (!mcpServers || typeof mcpServers !== "object") continue;
+
+      for (const [name, config] of Object.entries(mcpServers)) {
+        if (seen.has(name)) continue;
+        seen.add(name);
+
+        const hasCommand = typeof config.command === "string";
+        const hasUrl = typeof config.url === "string";
+        const transport: McpServerRawConfig["transport"] = hasCommand
+          ? "stdio"
+          : hasUrl
+            ? "http"
+            : "unknown";
+
+        servers.push({
+          name,
+          transport,
+          ...(hasCommand && {
+            command: config.command as string,
+            args: Array.isArray(config.args) ? (config.args as string[]) : undefined,
+          }),
+          ...(hasUrl && { url: config.url as string }),
+        });
+      }
+    } catch {
+      // Non-fatal — config file may not exist or be malformed
+    }
+  }
+
+  return servers;
+}
+
+// ─── Formatters (exported for testing) ──────────────────────────────────────
+
+export function formatMcpStatusReport(servers: McpServerStatus[]): string {
+  if (servers.length === 0) {
+    return [
+      "No MCP servers configured.",
+      "",
+      "Add servers to .mcp.json or .gsd/mcp.json to enable MCP integrations.",
+      "See: https://modelcontextprotocol.io/quickstart",
+    ].join("\n");
+  }
+
+  const lines: string[] = [`MCP Server Status — ${servers.length} server(s)\n`];
+
+  for (const s of servers) {
+    const icon = s.error ? "✗" : s.connected ? "✓" : "○";
+    const status = s.error
+      ? `error: ${s.error}`
+      : s.connected
+        ? `connected — ${s.toolCount} tools`
+        : "disconnected";
+    lines.push(`  ${icon} ${s.name} (${s.transport}) — ${status}`);
+  }
+
+  lines.push("");
+  lines.push("Use /gsd mcp check <server> for details on a specific server.");
+  lines.push("Use mcp_discover to connect and list tools for a server.");
+
+  return lines.join("\n");
+}
+
+export function formatMcpServerDetail(server: McpServerDetail): string {
+  const lines: string[] = [`MCP Server: ${server.name}\n`];
+
+  lines.push(`  Transport: ${server.transport}`);
+
+  if (server.error) {
+    lines.push(`  Status:    error`);
+    lines.push(`  Error:     ${server.error}`);
+  } else if (server.connected) {
+    lines.push(`  Status:    connected`);
+    lines.push(`  Tools:     ${server.toolCount}`);
+    if (server.tools.length > 0) {
+      lines.push("");
+      lines.push("  Available tools:");
+      for (const tool of server.tools) {
+        lines.push(`    - ${tool}`);
+      }
+    }
+  } else {
+    lines.push(`  Status:    disconnected`);
+    lines.push("");
+    lines.push(`  Run mcp_discover("${server.name}") to connect and list tools.`);
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Command handler ────────────────────────────────────────────────────────
+
+/**
+ * Handle `/gsd mcp [status|check <server>]`.
+ */
+export async function handleMcpStatus(
+  args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const trimmed = args.trim().toLowerCase();
+  const configs = readMcpConfigs();
+
+  // /gsd mcp check <server>
+  if (trimmed.startsWith("check ")) {
+    const serverName = args.trim().slice("check ".length).trim();
+    const config = configs.find((c) => c.name === serverName);
+    if (!config) {
+      const available = configs.map((c) => c.name).join(", ") || "(none)";
+      ctx.ui.notify(
+        `Unknown MCP server: "${serverName}"\n\nAvailable: ${available}`,
+        "warning",
+      );
+      return;
+    }
+
+    // Try to get connection/tool info from the mcp-client module if available
+    let connected = false;
+    let toolNames: string[] = [];
+    let error: string | undefined;
+    try {
+      const mcpClient = await import("../mcp-client/index.js");
+      // Access the module's connection state if exported; fall back gracefully
+      const mod = mcpClient as Record<string, unknown>;
+      if (typeof mod.getConnectionStatus === "function") {
+        const status = (mod.getConnectionStatus as (name: string) => { connected: boolean; tools: string[]; error?: string })(serverName);
+        connected = status.connected;
+        toolNames = status.tools;
+        error = status.error;
+      }
+    } catch {
+      // mcp-client may not expose status helpers — that's fine
+    }
+
+    ctx.ui.notify(
+      formatMcpServerDetail({
+        name: config.name,
+        transport: config.transport,
+        connected,
+        toolCount: toolNames.length,
+        tools: toolNames,
+        error,
+      }),
+      "info",
+    );
+    return;
+  }
+
+  // /gsd mcp or /gsd mcp status
+  if (!trimmed || trimmed === "status") {
+    // Build status for each server
+    const statuses: McpServerStatus[] = [];
+
+    for (const config of configs) {
+      let connected = false;
+      let toolCount = 0;
+      let error: string | undefined;
+
+      try {
+        const mcpClient = await import("../mcp-client/index.js");
+        const mod = mcpClient as Record<string, unknown>;
+        if (typeof mod.getConnectionStatus === "function") {
+          const status = (mod.getConnectionStatus as (name: string) => { connected: boolean; tools: string[]; error?: string })(config.name);
+          connected = status.connected;
+          toolCount = status.tools.length;
+          error = status.error;
+        }
+      } catch {
+        // Fall back to unknown state
+      }
+
+      statuses.push({
+        name: config.name,
+        transport: config.transport,
+        connected,
+        toolCount,
+        error,
+      });
+    }
+
+    ctx.ui.notify(formatMcpStatusReport(statuses), "info");
+    return;
+  }
+
+  // Unknown subcommand
+  ctx.ui.notify(
+    "Usage: /gsd mcp [status|check <server>]\n\n" +
+    "  status           Show all MCP server statuses (default)\n" +
+    "  check <server>   Detailed status for a specific server",
+    "warning",
+  );
+}

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -23,7 +23,6 @@ export interface LockData {
   unitType: string;
   unitId: string;
   unitStartedAt: string;
-  completedUnits: number;
   /** Path to the pi session JSONL file that was active when this unit started. */
   sessionFile?: string;
 }
@@ -37,7 +36,6 @@ export function writeLock(
   basePath: string,
   unitType: string,
   unitId: string,
-  completedUnits: number,
   sessionFile?: string,
 ): void {
   try {
@@ -47,7 +45,6 @@ export function writeLock(
       unitType,
       unitId,
       unitStartedAt: new Date().toISOString(),
-      completedUnits,
       sessionFile,
     };
     const lp = lockPath(basePath);
@@ -102,12 +99,11 @@ export function formatCrashInfo(lock: LockData): string {
     `Previous auto-mode session was interrupted.`,
     `  Was executing: ${lock.unitType} (${lock.unitId})`,
     `  Started at: ${lock.unitStartedAt}`,
-    `  Units completed before crash: ${lock.completedUnits}`,
     `  PID: ${lock.pid}`,
   ];
 
   // Add recovery guidance based on what was happening when it crashed
-  if (lock.unitType === "starting" && lock.unitId === "bootstrap" && lock.completedUnits === 0) {
+  if (lock.unitType === "starting" && lock.unitId === "bootstrap") {
     lines.push(`No work was lost. Run /gsd auto to restart.`);
   } else if (lock.unitType.includes("research") || lock.unitType.includes("plan")) {
     lines.push(`The ${lock.unitType} unit may be incomplete. Run /gsd auto to re-run it.`);

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -99,18 +99,11 @@ export class GSDDashboardOverlay {
     const currentUnit = dashData.currentUnit
       ? `${dashData.currentUnit.type}:${dashData.currentUnit.id}:${dashData.currentUnit.startedAt}`
       : "-";
-    const lastCompleted = dashData.completedUnits.length > 0
-      ? dashData.completedUnits[dashData.completedUnits.length - 1]
-      : null;
-    const completedKey = lastCompleted
-      ? `${dashData.completedUnits.length}:${lastCompleted.type}:${lastCompleted.id}:${lastCompleted.finishedAt}`
-      : "0";
     return [
       base,
       dashData.active ? "1" : "0",
       dashData.paused ? "1" : "0",
       currentUnit,
-      completedKey,
     ].join("|");
   }
 
@@ -458,49 +451,6 @@ export class GSDDashboardOverlay {
       lines.push(centered(th.fg("dim", "No active milestone.")));
     }
 
-    if (this.dashData.completedUnits.length > 0) {
-      lines.push(blank());
-      lines.push(hr());
-      lines.push(row(th.fg("text", th.bold("Completed"))));
-      lines.push(blank());
-
-      // Build ledger lookup for budget indicators (last entry wins for retries)
-      const ledgerLookup = new Map<string, UnitMetrics>();
-      const currentLedger = getLedger();
-      if (currentLedger) {
-        for (const lu of currentLedger.units) {
-          ledgerLookup.set(`${lu.type}:${lu.id}`, lu);
-        }
-      }
-
-      const recent = [...this.dashData.completedUnits].reverse().slice(0, 10);
-      for (const u of recent) {
-        // Budget indicators from ledger — use warning glyph for pressured units
-        const ledgerEntry = ledgerLookup.get(`${u.type}:${u.id}`);
-        const hadPressure = ledgerEntry?.continueHereFired === true;
-        const hadTruncation = (ledgerEntry?.truncationSections ?? 0) > 0;
-        const unitGlyph = hadPressure
-          ? th.fg(STATUS_COLOR.warning, STATUS_GLYPH.warning)
-          : th.fg(STATUS_COLOR.done, STATUS_GLYPH.done);
-        const left = `  ${unitGlyph} ${th.fg("muted", unitLabel(u.type))} ${th.fg("muted", u.id)}`;
-
-        let budgetMarkers = "";
-        if (hadTruncation) {
-          budgetMarkers += th.fg("warning", ` ▼${ledgerEntry!.truncationSections}`);
-        }
-        if (hadPressure) {
-          budgetMarkers += th.fg("error", " → wrap-up");
-        }
-
-        const right = th.fg("dim", formatDuration(u.finishedAt - u.startedAt));
-        lines.push(row(joinColumns(`${left}${budgetMarkers}`, right, contentWidth)));
-      }
-
-      if (this.dashData.completedUnits.length > 10) {
-        lines.push(row(th.fg("dim", `  ...and ${this.dashData.completedUnits.length - 10} more`)));
-      }
-    }
-
     const ledger = getLedger();
     if (ledger && ledger.units.length > 0) {
       const totals = getProjectTotals(ledger.units);

package/src/resources/extensions/gsd/db-writer.ts

@@ -9,11 +9,12 @@
 // parseDecisionsTable() and parseRequirementsSections() with field fidelity.
 
 import { join, resolve } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, statSync } from 'node:fs';
 import type { Decision, Requirement } from './types.js';
 import { resolveGsdRootFile } from './paths.js';
 import { saveFile } from './files.js';
 import { GSDError, GSD_STALE_STATE, GSD_IO_ERROR } from './errors.js';
+import { logWarning, logError } from './workflow-logger.js';
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
@@ -221,7 +222,7 @@ export async function nextDecisionId(): Promise<string> {
     const next = maxNum + 1;
     return `D${String(next).padStart(3, '0')}`;
   } catch (err) {
-    process.stderr.write(`gsd-db: nextDecisionId failed: ${(err as Error).message}\n`);
+    logError('manifest', 'nextDecisionId failed', { fn: 'nextDecisionId', error: String((err as Error).message) });
     return 'D001';
   }
 }
@@ -311,9 +312,7 @@ export async function saveDecisionToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      process.stderr.write(
-        `gsd-db: saveDecisionToDb — disk write failed, rolling back DB row: ${(diskErr as Error).message}\n`,
-      );
+      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).message) });
       adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
       throw diskErr;
     }
@@ -325,7 +324,7 @@ export async function saveDecisionToDb(
 
     return { id };
   } catch (err) {
-    process.stderr.write(`gsd-db: saveDecisionToDb failed: ${(err as Error).message}\n`);
+    logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String((err as Error).message) });
     throw err;
   }
 }
@@ -388,9 +387,7 @@ export async function updateRequirementInDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      process.stderr.write(
-        `gsd-db: updateRequirementInDb — disk write failed, reverting DB row: ${(diskErr as Error).message}\n`,
-      );
+      logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).message) });
       db.upsertRequirement(existing);
       throw diskErr;
     }
@@ -400,7 +397,7 @@ export async function updateRequirementInDb(
     clearPathCache();
     clearParseCache();
   } catch (err) {
-    process.stderr.write(`gsd-db: updateRequirementInDb failed: ${(err as Error).message}\n`);
+    logError('manifest', 'updateRequirementInDb failed', { fn: 'updateRequirementInDb', error: String((err as Error).message) });
     throw err;
   }
 }
@@ -428,30 +425,47 @@ export async function saveArtifactToDb(
   try {
     const db = await import('./gsd-db.js');
 
+    // Guard against path traversal before any reads/writes
+    const gsdDir = resolve(basePath, '.gsd');
+    const fullPath = resolve(basePath, '.gsd', opts.path);
+    if (!fullPath.startsWith(gsdDir)) {
+      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
+    }
+
+    // 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;
+    let skipDiskWrite = false;
+    if (existsSync(fullPath)) {
+      const existingSize = statSync(fullPath).size;
+      const newSize = Buffer.byteLength(opts.content, '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');
+        skipDiskWrite = true;
+      }
+    }
+
     db.insertArtifact({
       path: opts.path,
       artifact_type: opts.artifact_type,
       milestone_id: opts.milestone_id ?? null,
       slice_id: opts.slice_id ?? null,
       task_id: opts.task_id ?? null,
-      full_content: opts.content,
+      full_content: dbContent,
     });
 
-    // Write the file to disk (guard against path traversal)
-    const gsdDir = resolve(basePath, '.gsd');
-    const fullPath = resolve(basePath, '.gsd', opts.path);
-    if (!fullPath.startsWith(gsdDir)) {
-      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
-    }
-    try {
-      await saveFile(fullPath, opts.content);
-    } catch (diskErr) {
-      process.stderr.write(
-        `gsd-db: saveArtifactToDb — disk write failed, rolling back DB row: ${(diskErr as Error).message}\n`,
-      );
-      const rollbackAdapter = db._getAdapter();
-      rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
-      throw diskErr;
+    // Write the file to disk (only if we're not preserving a richer existing file)
+    if (!skipDiskWrite) {
+      try {
+        await saveFile(fullPath, opts.content);
+      } catch (diskErr) {
+        logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String((diskErr as Error).message) });
+        const rollbackAdapter = db._getAdapter();
+        rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
+        throw diskErr;
+      }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -459,7 +473,7 @@ export async function saveArtifactToDb(
     clearPathCache();
     clearParseCache();
   } catch (err) {
-    process.stderr.write(`gsd-db: saveArtifactToDb failed: ${(err as Error).message}\n`);
+    logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String((err as Error).message) });
     throw err;
   }
 }