gsd-pi 2.44.0-dev.0b97ffd → 2.44.0-dev.73f2fd5

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -1307,6 +1307,12 @@ export async function buildCompleteMilestonePrompt(
     roadmapPath: roadmapRel,
     inlinedContext,
     milestoneSummaryPath,
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      extraContext: [inlinedContext],
+    }),
   });
 }
 
@@ -1390,6 +1396,12 @@ export async function buildValidateMilestonePrompt(
     inlinedContext,
     validationPath: validationOutputPath,
     remediationRound: String(remediationRound),
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      extraContext: [inlinedContext],
+    }),
   });
 }
 
@@ -1500,6 +1512,12 @@ export async function buildRunUatPrompt(
     uatResultPath,
     uatType,
     inlinedContext,
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      sliceId,
+      extraContext: [inlinedContext],
+    }),
   });
 }
 
@@ -1552,11 +1570,16 @@ export async function buildReassessRoadmapPrompt(
     milestoneTitle: midTitle,
     completedSliceId,
     roadmapPath: roadmapRel,
-    completedSliceSummaryPath: summaryRel,
     assessmentPath,
     inlinedContext,
     deferredCaptures,
     commitInstruction: reassessCommitInstruction,
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      extraContext: [inlinedContext, deferredCaptures],
+    }),
   });
 }
 

package/src/resources/extensions/gsd/auto-timers.ts

@@ -8,6 +8,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "./unit-runtime.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { resolveAutoSupervisorConfig } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
 import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
@@ -32,6 +33,8 @@ export interface SupervisionContext {
   buildSnapshotOpts: () => CloseoutOptions & Record<string, unknown>;
   buildRecoveryContext: () => RecoveryContext;
   pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>;
+  /** Optional task estimate string (e.g. "30m", "2h") for timeout scaling (#2243). */
+  taskEstimate?: string;
 }
 
 /**
@@ -41,13 +44,71 @@ export interface SupervisionContext {
  * 3. Hard timeout (pause + recovery)
  * 4. Context-pressure monitor (continue-here)
  */
+
+/**
+ * Parse a task estimate string (e.g. "30m", "2h", "1h30m") into minutes.
+ * Returns null if the string cannot be parsed.
+ */
+export function parseEstimateMinutes(estimate: string): number | null {
+  if (!estimate || typeof estimate !== "string") return null;
+  const trimmed = estimate.trim();
+  if (!trimmed) return null;
+
+  let totalMinutes = 0;
+  let matched = false;
+
+  // Match hours component
+  const hoursMatch = trimmed.match(/(\d+)\s*h/i);
+  if (hoursMatch) {
+    totalMinutes += Number(hoursMatch[1]) * 60;
+    matched = true;
+  }
+
+  // Match minutes component
+  const minutesMatch = trimmed.match(/(\d+)\s*m/i);
+  if (minutesMatch) {
+    totalMinutes += Number(minutesMatch[1]);
+    matched = true;
+  }
+
+  return matched ? totalMinutes : null;
+}
+
 export function startUnitSupervision(sctx: SupervisionContext): void {
   const { s, ctx, pi, unitType, unitId, prefs, buildSnapshotOpts, buildRecoveryContext, pauseAuto } = sctx;
 
   const supervisor = resolveAutoSupervisorConfig();
-  const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000;
-  const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;
-  const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000;
+
+  // Scale timeouts based on task estimate annotations (#2243).
+  // If the task has an est: annotation, use it to extend the hard and soft timeouts
+  // so longer tasks don't get prematurely timed out.
+  let taskEstimate = sctx.taskEstimate;
+  if (!taskEstimate && unitType === "task" && isDbAvailable()) {
+    // Look up the task estimate from the DB (#2243).
+    try {
+      if (s.currentMilestoneId) {
+        const slices = getMilestoneSlices(s.currentMilestoneId);
+        for (const slice of slices) {
+          const tasks = getSliceTasks(s.currentMilestoneId, slice.id);
+          const task = tasks.find(t => t.id === unitId);
+          if (task?.estimate) {
+            taskEstimate = task.estimate;
+            break;
+          }
+        }
+      }
+    } catch {
+      // Non-fatal — fall through with no estimate
+    }
+  }
+  const estimateMinutes = taskEstimate ? parseEstimateMinutes(taskEstimate) : null;
+  const timeoutScale = estimateMinutes && estimateMinutes > 0
+    ? Math.max(1, estimateMinutes / 10)  // 10min task = 1x, 30min = 3x, 2h = 12x
+    : 1;
+
+  const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
+  const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;  // idle not scaled — idle is idle
+  const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
 
   // ── 1. Soft timeout warning ──
   s.wrapupWarningHandle = setTimeout(() => {

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -93,6 +93,11 @@ export function syncStateToProjectRoot(
     { force: true },
   );
 
+  // 3. metrics.json — session cost/token tracking (#2313).
+  // Without this, metrics accumulated in the worktree are invisible from the
+  // project root and never appear in the dashboard or skill-health reports.
+  safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
+
   // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
   // Without this, a crash during a unit leaves the runtime record only in the
   // worktree. If the next session resolves basePath before worktree re-entry,

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -162,6 +162,7 @@ export function syncGsdStateToWorktree(
     "OVERRIDES.md",
     "QUEUE.md",
     "completed-units.json",
+    "metrics.json",
   ];
   for (const f of rootFiles) {
     const src = join(mainGsd, f);
@@ -325,8 +326,9 @@ export function syncWorktreeStateBack(
   // ── 1. Sync root-level .gsd/ files back ──────────────────────────────
   // The worktree is authoritative — complete-milestone updates REQUIREMENTS,
   // PROJECT, etc. These must overwrite main's copies so they survive teardown.
-  // Also includes QUEUE.md and completed-units.json which are written during
-  // milestone closeout and lost on teardown without explicit sync (#1787).
+  // Also includes QUEUE.md, completed-units.json, and metrics.json which are
+  // written during milestone closeout and lost on teardown without explicit sync
+  // (#1787, #2313).
   const rootFiles = [
     "DECISIONS.md",
     "REQUIREMENTS.md",
@@ -335,6 +337,7 @@ export function syncWorktreeStateBack(
     "OVERRIDES.md",
     "QUEUE.md",
     "completed-units.json",
+    "metrics.json",
   ];
   for (const f of rootFiles) {
     const src = join(wtGsd, f);
@@ -1320,9 +1323,9 @@ export function mergeMilestoneToMain(
     }
   }
 
-  // 9b. Auto-create PR if enabled (requires push_branches + push succeeded)
+  // 9b. Auto-create PR if enabled (#2302: no longer gated on pushed/auto_push)
   let prCreated = false;
-  if (prefs.auto_pr === true && pushed) {
+  if (prefs.auto_pr === true && !nothingToCommit) {
     const remote = prefs.remote ?? "origin";
     const prTarget = prefs.pr_target_branch ?? mainBranch;
     try {
@@ -1332,9 +1335,9 @@ export function mergeMilestoneToMain(
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf-8",
       });
-      // Create PR via gh CLI
+      // Create PR via gh CLI with explicit --head and --base (#2302)
       execFileSync("gh", [
-        "pr", "create",
+        "pr", "create", "--draft",
         "--base", prTarget,
         "--head", milestoneBranch,
         "--title", `Milestone ${milestoneId} complete`,

package/src/resources/extensions/gsd/auto.ts

@@ -610,14 +610,48 @@ export async function stopAuto(
     }
 
     // ── Step 4: Auto-worktree exit ──
+    // When the milestone is complete (has a SUMMARY), merge the worktree branch
+    // back to main so code isn't stranded on the worktree branch (#2317).
+    // For incomplete milestones, preserve the branch for later resumption.
     try {
       if (s.currentMilestoneId) {
         const notifyCtx = ctx
           ? { notify: ctx.ui.notify.bind(ctx.ui) }
           : { notify: () => {} };
-        buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
-          preserveBranch: true,
-        });
+        const resolver = buildResolver();
+
+        // Check if the milestone is complete — SUMMARY file is the authoritative signal.
+        let milestoneComplete = false;
+        try {
+          const summaryPath = resolveMilestoneFile(
+            s.originalBasePath || s.basePath,
+            s.currentMilestoneId,
+            "SUMMARY",
+          );
+          if (!summaryPath) {
+            // Also check in the worktree path (SUMMARY may not be synced yet)
+            const wtSummaryPath = resolveMilestoneFile(
+              s.basePath,
+              s.currentMilestoneId,
+              "SUMMARY",
+            );
+            milestoneComplete = wtSummaryPath !== null;
+          } else {
+            milestoneComplete = true;
+          }
+        } catch {
+          // Non-fatal — fall through to preserveBranch path
+        }
+
+        if (milestoneComplete) {
+          // Milestone is complete — merge worktree branch back to main
+          resolver.mergeAndExit(s.currentMilestoneId, notifyCtx);
+        } else {
+          // Milestone still in progress — preserve branch for later resumption
+          resolver.exitMilestone(s.currentMilestoneId, notifyCtx, {
+            preserveBranch: true,
+          });
+        }
       }
     } catch (e) {
       debugLog("stop-cleanup-worktree", { error: e instanceof Error ? e.message : String(e) });

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Text } from "@gsd/pi-tui";
 
 import { findMilestoneIds, nextMilestoneId, claimReservedId, getReservedMilestoneIds } from "../guided-flow.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
@@ -87,6 +88,22 @@ export function registerDbTools(pi: ExtensionAPI): void {
       ], { description: "Who made this decision: 'human' (user directed), 'agent' (LLM decided autonomously), or 'collaborative' (discussed and agreed). Default: 'agent'" })),
     }),
     execute: decisionSaveExecute,
+    renderCall(args: any, theme: any) {
+      let text = theme.fg("toolTitle", theme.bold("decision_save "));
+      if (args.scope) text += theme.fg("accent", `[${args.scope}] `);
+      if (args.decision) text += theme.fg("muted", args.decision);
+      if (args.choice) text += theme.fg("dim", ` — ${args.choice}`);
+      return new Text(text, 0, 0);
+    },
+    renderResult(result: any, _options: any, theme: any) {
+      const d = result.details;
+      if (result.isError || d?.error) {
+        return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+      }
+      let text = theme.fg("success", `Decision ${d?.id ?? ""} saved`);
+      if (d?.id) text += theme.fg("dim", ` → DECISIONS.md`);
+      return new Text(text, 0, 0);
+    },
   };
 
   pi.registerTool(decisionSaveTool);
@@ -157,6 +174,22 @@ export function registerDbTools(pi: ExtensionAPI): void {
       supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
     }),
     execute: requirementUpdateExecute,
+    renderCall(args: any, theme: any) {
+      let text = theme.fg("toolTitle", theme.bold("requirement_update "));
+      if (args.id) text += theme.fg("accent", args.id);
+      const fields = ["status", "validation", "notes", "description"].filter((f) => args[f]);
+      if (fields.length > 0) text += theme.fg("dim", ` (${fields.join(", ")})`);
+      return new Text(text, 0, 0);
+    },
+    renderResult(result: any, _options: any, theme: any) {
+      const d = result.details;
+      if (result.isError || d?.error) {
+        return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+      }
+      let text = theme.fg("success", `Requirement ${d?.id ?? ""} updated`);
+      text += theme.fg("dim", ` → REQUIREMENTS.md`);
+      return new Text(text, 0, 0);
+    },
   };
 
   pi.registerTool(requirementUpdateTool);
@@ -235,6 +268,22 @@ export function registerDbTools(pi: ExtensionAPI): void {
       content: Type.String({ description: "The full markdown content of the artifact" }),
     }),
     execute: summarySaveExecute,
+    renderCall(args: any, theme: any) {
+      let text = theme.fg("toolTitle", theme.bold("summary_save "));
+      if (args.artifact_type) text += theme.fg("accent", args.artifact_type);
+      const path = [args.milestone_id, args.slice_id, args.task_id].filter(Boolean).join("/");
+      if (path) text += theme.fg("dim", ` ${path}`);
+      return new Text(text, 0, 0);
+    },
+    renderResult(result: any, _options: any, theme: any) {
+      const d = result.details;
+      if (result.isError || d?.error) {
+        return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+      }
+      let text = theme.fg("success", `${d?.artifact_type ?? "Artifact"} saved`);
+      if (d?.path) text += theme.fg("dim", ` → ${d.path}`);
+      return new Text(text, 0, 0);
+    },
   };
 
   pi.registerTool(summarySaveTool);
@@ -248,6 +297,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       // This guarantees the ID shown in the UI matches the one materialised on disk.
       const reserved = claimReservedId();
       if (reserved) {
+        await ensureMilestoneDbRow(reserved);
         return {
           content: [{ type: "text" as const, text: reserved }],
           details: { operation: "generate_milestone_id", id: reserved, source: "reserved" } as any,
@@ -259,6 +309,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
       const allIds = [...new Set([...existingIds, ...getReservedMilestoneIds()])];
       const newId = nextMilestoneId(allIds, uniqueEnabled);
+      await ensureMilestoneDbRow(newId);
       return {
         content: [{ type: "text" as const, text: newId }],
         details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, uniqueEnabled } as any,
@@ -272,6 +323,23 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
   };
 
+  /**
+   * Insert a minimal DB row for a milestone ID so it's visible to the state
+   * machine. Uses INSERT OR IGNORE — safe to call even if gsd_plan_milestone
+   * later writes the full row. Silently skips if the DB isn't available yet
+   * (pre-migration).
+   */
+  async function ensureMilestoneDbRow(milestoneId: string): Promise<void> {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) return;
+    try {
+      const { insertMilestone } = await import("../gsd-db.js");
+      insertMilestone({ id: milestoneId, status: "queued" });
+    } catch {
+      // Non-fatal — the safety-net in deriveStateFromDb will catch this
+    }
+  }
+
   const milestoneGenerateIdTool = {
     name: "gsd_milestone_generate_id",
     label: "Generate Milestone ID",
@@ -288,6 +356,18 @@ export function registerDbTools(pi: ExtensionAPI): void {
     ],
     parameters: Type.Object({}),
     execute: milestoneGenerateIdExecute,
+    renderCall(_args: any, theme: any) {
+      return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
+    },
+    renderResult(result: any, _options: any, theme: any) {
+      const d = result.details;
+      if (result.isError || d?.error) {
+        return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+      }
+      let text = theme.fg("success", `Generated ${d?.id ?? "ID"}`);
+      if (d?.source === "reserved") text += theme.fg("dim", " (reserved)");
+      return new Text(text, 0, 0);
+    },
   };
 
   pi.registerTool(milestoneGenerateIdTool);
@@ -794,6 +874,74 @@ export function registerDbTools(pi: ExtensionAPI): void {
   pi.registerTool(milestoneCompleteTool);
   registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
 
+  // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
+
+  const milestoneValidateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot validate milestone." }],
+        details: { operation: "validate_milestone", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleValidateMilestone } = await import("../tools/validate-milestone.js");
+      const result = await handleValidateMilestone(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error validating milestone: ${result.error}` }],
+          details: { operation: "validate_milestone", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Validated milestone ${result.milestoneId} — verdict: ${result.verdict}. Written to ${result.validationPath}` }],
+        details: {
+          operation: "validate_milestone",
+          milestoneId: result.milestoneId,
+          verdict: result.verdict,
+          validationPath: result.validationPath,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`gsd-db: validate_milestone tool failed: ${msg}\n`);
+      return {
+        content: [{ type: "text" as const, text: `Error validating milestone: ${msg}` }],
+        details: { operation: "validate_milestone", error: msg } as any,
+      };
+    }
+  };
+
+  const milestoneValidateTool = {
+    name: "gsd_validate_milestone",
+    label: "Validate Milestone",
+    description:
+      "Validate a milestone before completion — persist validation results to the DB, render VALIDATION.md to disk. " +
+      "Records verdict (pass/needs-attention/needs-remediation) and rationale.",
+    promptSnippet: "Validate a GSD milestone (DB write + VALIDATION.md render)",
+    promptGuidelines: [
+      "Use gsd_validate_milestone when all slices are done and the milestone needs validation before completion.",
+      "Parameters: milestoneId, verdict, remediationRound, successCriteriaChecklist, sliceDeliveryAudit, crossSliceIntegration, requirementCoverage, verdictRationale, remediationPlan (optional).",
+      "If verdict is 'needs-remediation', also provide remediationPlan and use gsd_reassess_roadmap to add remediation slices to the roadmap.",
+      "On success, returns validationPath where VALIDATION.md was written.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      verdict: StringEnum(["pass", "needs-attention", "needs-remediation"], { description: "Validation verdict" }),
+      remediationRound: Type.Number({ description: "Remediation round (0 for first validation)" }),
+      successCriteriaChecklist: Type.String({ description: "Markdown checklist of success criteria with pass/fail and evidence" }),
+      sliceDeliveryAudit: Type.String({ description: "Markdown table auditing each slice's claimed vs delivered output" }),
+      crossSliceIntegration: Type.String({ description: "Markdown describing any cross-slice boundary mismatches" }),
+      requirementCoverage: Type.String({ description: "Markdown describing any unaddressed requirements" }),
+      verdictRationale: Type.String({ description: "Why this verdict was chosen" }),
+      remediationPlan: Type.Optional(Type.String({ description: "Remediation plan (required if verdict is needs-remediation)" })),
+    }),
+    execute: milestoneValidateExecute,
+  };
+
+  pi.registerTool(milestoneValidateTool);
+  registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
+
   // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
 
   const replanSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {

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";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -68,6 +68,7 @@ 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: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
 ];
 
@@ -187,6 +188,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/handlers/core.ts

@@ -53,6 +53,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,6 +191,11 @@ 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);