gsd-pi 2.61.0-dev.7aed0bf → 2.62.0-dev.a987556

package/packages/mcp-server/src/readers/roadmap.ts

@@ -0,0 +1,263 @@
+// GSD MCP Server — roadmap structure reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import {
+  resolveGsdRoot,
+  findMilestoneIds,
+  resolveMilestoneFile,
+  findSliceIds,
+  resolveSliceFile,
+  findTaskFiles,
+} from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TaskInfo {
+  id: string;
+  title: string;
+  status: 'done' | 'pending';
+}
+
+export interface SliceInfo {
+  id: string;
+  title: string;
+  status: 'done' | 'active' | 'pending';
+  risk: string;
+  depends: string[];
+  demo: string;
+  tasks: TaskInfo[];
+}
+
+export interface MilestoneInfo {
+  id: string;
+  title: string;
+  status: 'done' | 'active' | 'pending' | 'parked';
+  vision: string;
+  slices: SliceInfo[];
+}
+
+export interface RoadmapResult {
+  milestones: MilestoneInfo[];
+}
+
+// ---------------------------------------------------------------------------
+// ROADMAP.md table parser
+// ---------------------------------------------------------------------------
+
+function parseRoadmapTable(content: string): Array<{
+  id: string; title: string; risk: string; depends: string[]; done: boolean; demo: string;
+}> {
+  const results: Array<{
+    id: string; title: string; risk: string; depends: string[]; done: boolean; demo: string;
+  }> = [];
+
+  // Try table format first: | S01 | Title | risk | depends | done-icon | demo |
+  const tableSection = content.match(/## (?:Slice[s]?|Slice Overview|Slice Table)\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (tableSection) {
+    const lines = tableSection[1].split('\n');
+    for (const line of lines) {
+      if (!line.includes('|')) continue;
+      const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
+      if (cells.length < 4) continue;
+      if (cells[0] === 'ID' || cells[0].startsWith('--')) continue;
+
+      const id = cells[0].match(/S\d+/)?.[0];
+      if (!id) continue;
+
+      const done = cells.some((c) => c === '\u2611' || c === '\u2705' || c.toLowerCase() === 'done');
+      const depends = (cells[3] ?? '').replace(/\u2014/g, '').split(',').map((d) => d.trim()).filter(Boolean);
+
+      results.push({
+        id,
+        title: cells[1] ?? '',
+        risk: cells[2] ?? 'medium',
+        depends,
+        done,
+        demo: cells[5] ?? '',
+      });
+    }
+    if (results.length > 0) return results;
+  }
+
+  // Try checkbox format: - [x] **S01: Title** `risk:high` `depends:[S01]`
+  const checkboxRe = /^-\s+\[([ xX])\]\s+\*\*(S\d+):\s*(.+?)\*\*(?:.*?`risk:(\w+)`)?(?:.*?`depends:\[([^\]]*)\]`)?/gm;
+  let match: RegExpExecArray | null;
+  while ((match = checkboxRe.exec(content)) !== null) {
+    const [, checked, id, title, risk, deps] = match;
+    results.push({
+      id,
+      title: title.trim(),
+      risk: risk ?? 'medium',
+      depends: deps ? deps.split(',').map((d) => d.trim()).filter(Boolean) : [],
+      done: checked !== ' ',
+      demo: '',
+    });
+  }
+  if (results.length > 0) return results;
+
+  // Try prose headers: ## S01: Title
+  const headerRe = /^##\s+(S\d+):\s*(.+)/gm;
+  while ((match = headerRe.exec(content)) !== null) {
+    results.push({
+      id: match[1],
+      title: match[2].trim(),
+      risk: 'medium',
+      depends: [],
+      done: false,
+      demo: '',
+    });
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// PLAN.md task parser
+// ---------------------------------------------------------------------------
+
+function parseSlicePlanTasks(content: string): Array<{ id: string; title: string; done: boolean }> {
+  const results: Array<{ id: string; title: string; done: boolean }> = [];
+
+  // Checkbox format: - [x] **T01: Title** — description
+  const taskRe = /^-\s+\[([ xX])\]\s+\*\*(T\d+):\s*(.+?)\*\*/gm;
+  let match: RegExpExecArray | null;
+  while ((match = taskRe.exec(content)) !== null) {
+    results.push({
+      id: match[2],
+      title: match[3].trim(),
+      done: match[1] !== ' ',
+    });
+  }
+  if (results.length > 0) return results;
+
+  // H3 format: ### T01: Title
+  const h3Re = /^###\s+(T\d+):\s*(.+)/gm;
+  while ((match = h3Re.exec(content)) !== null) {
+    results.push({
+      id: match[1],
+      title: match[2].trim(),
+      done: false,
+    });
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Milestone title from CONTEXT.md or ROADMAP.md H1
+// ---------------------------------------------------------------------------
+
+function readMilestoneTitle(gsdRoot: string, mid: string): string {
+  const ctxPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT');
+  if (ctxPath && existsSync(ctxPath)) {
+    const content = readFileSync(ctxPath, 'utf-8');
+    const h1 = content.match(/^#\s+(?:M\d+:?\s*)?(.+)/m);
+    if (h1) return h1[1].trim();
+  }
+
+  const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP');
+  if (roadmapPath && existsSync(roadmapPath)) {
+    const content = readFileSync(roadmapPath, 'utf-8');
+    const h1 = content.match(/^#\s+(?:M\d+:?\s*)?(.+)/m);
+    if (h1) return h1[1].trim();
+  }
+
+  return mid;
+}
+
+function readVision(gsdRoot: string, mid: string): string {
+  const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP');
+  if (!roadmapPath || !existsSync(roadmapPath)) return '';
+
+  const content = readFileSync(roadmapPath, 'utf-8');
+  const section = content.match(/## Vision\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  return section ? section[1].trim() : '';
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function readRoadmap(projectDir: string, filterMilestoneId?: string): RoadmapResult {
+  const gsd = resolveGsdRoot(projectDir);
+  let milestoneIds = findMilestoneIds(gsd);
+
+  if (filterMilestoneId) {
+    milestoneIds = milestoneIds.filter((id) => id === filterMilestoneId);
+  }
+
+  const milestones: MilestoneInfo[] = [];
+
+  for (const mid of milestoneIds) {
+    const title = readMilestoneTitle(gsd, mid);
+    const vision = readVision(gsd, mid);
+
+    const summaryPath = resolveMilestoneFile(gsd, mid, 'SUMMARY');
+    const hasSummary = summaryPath !== null && existsSync(summaryPath);
+
+    const roadmapPath = resolveMilestoneFile(gsd, mid, 'ROADMAP');
+    let roadmapSlices: ReturnType<typeof parseRoadmapTable> = [];
+    if (roadmapPath && existsSync(roadmapPath)) {
+      roadmapSlices = parseRoadmapTable(readFileSync(roadmapPath, 'utf-8'));
+    }
+
+    const fsSliceIds = findSliceIds(gsd, mid);
+    const sliceIdSet = new Set([
+      ...roadmapSlices.map((s) => s.id),
+      ...fsSliceIds,
+    ]);
+
+    const slices: SliceInfo[] = [];
+    for (const sid of Array.from(sliceIdSet).sort()) {
+      const roadmapEntry = roadmapSlices.find((s) => s.id === sid);
+      const taskFiles = findTaskFiles(gsd, mid, sid);
+
+      const planPath = resolveSliceFile(gsd, mid, sid, 'PLAN');
+      let planTasks: ReturnType<typeof parseSlicePlanTasks> = [];
+      if (planPath && existsSync(planPath)) {
+        planTasks = parseSlicePlanTasks(readFileSync(planPath, 'utf-8'));
+      }
+
+      const tasks: TaskInfo[] = [];
+      const seenIds = new Set<string>();
+
+      for (const pt of planTasks) {
+        const fsTask = taskFiles.find((t) => t.id === pt.id);
+        const done = fsTask?.hasSummary ?? pt.done;
+        tasks.push({ id: pt.id, title: pt.title, status: done ? 'done' : 'pending' });
+        seenIds.add(pt.id);
+      }
+      for (const ft of taskFiles) {
+        if (seenIds.has(ft.id)) continue;
+        tasks.push({ id: ft.id, title: ft.id, status: ft.hasSummary ? 'done' : 'pending' });
+      }
+
+      const allDone = tasks.length > 0 && tasks.every((t) => t.status === 'done');
+      const anyDone = tasks.some((t) => t.status === 'done');
+      const sliceStatus: SliceInfo['status'] = allDone ? 'done' : anyDone ? 'active' : 'pending';
+
+      slices.push({
+        id: sid,
+        title: roadmapEntry?.title ?? sid,
+        status: sliceStatus,
+        risk: roadmapEntry?.risk ?? 'medium',
+        depends: roadmapEntry?.depends ?? [],
+        demo: roadmapEntry?.demo ?? '',
+        tasks,
+      });
+    }
+
+    const allSlicesDone = slices.length > 0 && slices.every((s) => s.status === 'done');
+    const anySliceActive = slices.some((s) => s.status === 'active' || s.status === 'done');
+    const milestoneStatus: MilestoneInfo['status'] = hasSummary
+      ? 'done'
+      : allSlicesDone ? 'done' : anySliceActive ? 'active' : 'pending';
+
+    milestones.push({ id: mid, title, status: milestoneStatus, vision, slices });
+  }
+
+  return { milestones };
+}

package/packages/mcp-server/src/readers/state.ts

@@ -0,0 +1,223 @@
+// GSD MCP Server — project state reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import {
+  resolveGsdRoot,
+  resolveRootFile,
+  findMilestoneIds,
+  resolveMilestoneDir,
+  resolveMilestoneFile,
+  findSliceIds,
+  findTaskFiles,
+} from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProgressResult {
+  activeMilestone: { id: string; title: string } | null;
+  activeSlice: { id: string; title: string } | null;
+  activeTask: { id: string; title: string } | null;
+  phase: string;
+  milestones: { total: number; done: number; active: number; pending: number; parked: number };
+  slices: { total: number; done: number; active: number; pending: number };
+  tasks: { total: number; done: number; pending: number };
+  requirements: { active: number; validated: number; deferred: number; outOfScope: number } | null;
+  blockers: string[];
+  nextAction: string;
+}
+
+// ---------------------------------------------------------------------------
+// STATE.md parser
+// ---------------------------------------------------------------------------
+
+function parseBoldField(content: string, label: string): string | null {
+  const re = new RegExp(`\\*\\*${label}:\\*\\*\\s*(.+)`, 'i');
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function parseActiveRef(value: string | null): { id: string; title: string } | null {
+  if (!value || value.toLowerCase() === 'none' || value === '—') return null;
+  // "M001: Flight Simulator" or "M001"
+  const m = value.match(/^(M\d+|S\d+|T\d+):?\s*(.*)/);
+  if (m) return { id: m[1], title: m[2] || m[1] };
+  return { id: value, title: value };
+}
+
+function parsePhase(value: string | null): string {
+  if (!value) return 'unknown';
+  const lower = value.toLowerCase().trim();
+  if (lower.includes('research') || lower.includes('discuss')) return 'research';
+  if (lower.includes('plan')) return 'plan';
+  if (lower.includes('execut')) return 'execute';
+  if (lower.includes('complete') || lower.includes('done')) return 'complete';
+  return lower;
+}
+
+function parseRequirementsLine(value: string | null): ProgressResult['requirements'] | null {
+  if (!value) return null;
+  const active = value.match(/(\d+)\s*active/i);
+  const validated = value.match(/(\d+)\s*validated/i);
+  const deferred = value.match(/(\d+)\s*deferred/i);
+  const outOfScope = value.match(/(\d+)\s*out.of.scope/i);
+  if (!active && !validated && !deferred && !outOfScope) return null;
+  return {
+    active: active ? parseInt(active[1], 10) : 0,
+    validated: validated ? parseInt(validated[1], 10) : 0,
+    deferred: deferred ? parseInt(deferred[1], 10) : 0,
+    outOfScope: outOfScope ? parseInt(outOfScope[1], 10) : 0,
+  };
+}
+
+function parseBlockers(content: string): string[] {
+  const section = content.match(/## Blockers\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (!section) return [];
+  return section[1]
+    .split('\n')
+    .map((l) => l.replace(/^[-*]\s*/, '').trim())
+    .filter(Boolean);
+}
+
+function parseNextAction(content: string): string {
+  const section = content.match(/## Next Action\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (!section) return '';
+  return section[1].trim().split('\n')[0] || '';
+}
+
+// ---------------------------------------------------------------------------
+// Milestone registry from STATE.md
+// ---------------------------------------------------------------------------
+
+interface RegistryEntry { id: string; status: 'done' | 'active' | 'pending' | 'parked' }
+
+function parseMilestoneRegistry(content: string): RegistryEntry[] {
+  const section = content.match(/## Milestone Registry\s*\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (!section) return [];
+  const entries: RegistryEntry[] = [];
+  for (const line of section[1].split('\n')) {
+    const m = line.match(/[-*]\s*(☑|✅|🔄|⬜|⏸)\s*\*\*(M\d+):\*\*/);
+    if (!m) continue;
+    const [, icon, id] = m;
+    let status: RegistryEntry['status'] = 'pending';
+    if (icon === '☑' || icon === '✅') status = 'done';
+    else if (icon === '🔄') status = 'active';
+    else if (icon === '⏸') status = 'parked';
+    entries.push({ id, status });
+  }
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Count slices/tasks by walking filesystem
+// ---------------------------------------------------------------------------
+
+function countSlicesAndTasks(gsdRoot: string, milestoneIds: string[]): {
+  slices: ProgressResult['slices'];
+  tasks: ProgressResult['tasks'];
+} {
+  let sliceTotal = 0, sliceDone = 0, sliceActive = 0;
+  let taskTotal = 0, taskDone = 0;
+
+  for (const mid of milestoneIds) {
+    const sliceIds = findSliceIds(gsdRoot, mid);
+    sliceTotal += sliceIds.length;
+
+    for (const sid of sliceIds) {
+      const tasks = findTaskFiles(gsdRoot, mid, sid);
+      taskTotal += tasks.length;
+
+      const allDone = tasks.length > 0 && tasks.every((t) => t.hasSummary);
+      const anyDone = tasks.some((t) => t.hasSummary);
+
+      if (allDone) {
+        sliceDone++;
+        taskDone += tasks.length;
+      } else {
+        if (anyDone) sliceActive++;
+        taskDone += tasks.filter((t) => t.hasSummary).length;
+      }
+    }
+  }
+
+  return {
+    slices: {
+      total: sliceTotal,
+      done: sliceDone,
+      active: sliceActive,
+      pending: sliceTotal - sliceDone - sliceActive,
+    },
+    tasks: { total: taskTotal, done: taskDone, pending: taskTotal - taskDone },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function readProgress(projectDir: string): ProgressResult {
+  const gsd = resolveGsdRoot(projectDir);
+  const statePath = resolveRootFile(gsd, 'STATE.md');
+
+  // Defaults
+  const result: ProgressResult = {
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: 'unknown',
+    milestones: { total: 0, done: 0, active: 0, pending: 0, parked: 0 },
+    slices: { total: 0, done: 0, active: 0, pending: 0 },
+    tasks: { total: 0, done: 0, pending: 0 },
+    requirements: null,
+    blockers: [],
+    nextAction: '',
+  };
+
+  if (!existsSync(statePath)) {
+    // No STATE.md — derive from filesystem only
+    const milestoneIds = findMilestoneIds(gsd);
+    result.milestones.total = milestoneIds.length;
+    result.milestones.pending = milestoneIds.length;
+    const counts = countSlicesAndTasks(gsd, milestoneIds);
+    result.slices = counts.slices;
+    result.tasks = counts.tasks;
+    return result;
+  }
+
+  const content = readFileSync(statePath, 'utf-8');
+
+  // Parse STATE.md fields
+  result.activeMilestone = parseActiveRef(parseBoldField(content, 'Active Milestone'));
+  result.activeSlice = parseActiveRef(parseBoldField(content, 'Active Slice'));
+  result.activeTask = parseActiveRef(parseBoldField(content, 'Active Task'));
+  result.phase = parsePhase(parseBoldField(content, 'Phase'));
+  result.requirements = parseRequirementsLine(parseBoldField(content, 'Requirements Status'));
+  result.blockers = parseBlockers(content);
+  result.nextAction = parseNextAction(content);
+
+  // Milestone counts from registry
+  const registry = parseMilestoneRegistry(content);
+  if (registry.length > 0) {
+    result.milestones.total = registry.length;
+    result.milestones.done = registry.filter((e) => e.status === 'done').length;
+    result.milestones.active = registry.filter((e) => e.status === 'active').length;
+    result.milestones.parked = registry.filter((e) => e.status === 'parked').length;
+    result.milestones.pending = registry.length -
+      result.milestones.done - result.milestones.active - result.milestones.parked;
+  } else {
+    // Fallback: count directories
+    const milestoneIds = findMilestoneIds(gsd);
+    result.milestones.total = milestoneIds.length;
+    result.milestones.pending = milestoneIds.length;
+  }
+
+  // Slice/task counts from filesystem
+  const milestoneIds = findMilestoneIds(gsd);
+  const counts = countSlicesAndTasks(gsd, milestoneIds);
+  result.slices = counts.slices;
+  result.tasks = counts.tasks;
+
+  return result;
+}

package/packages/mcp-server/src/server.ts

@@ -1,5 +1,8 @@
 /**
- * MCP Server — registers 6 GSD orchestration tools on McpServer.
+ * MCP Server — registers GSD orchestration + read-only project state tools.
+ *
+ * Session tools (6): gsd_execute, gsd_status, gsd_result, gsd_cancel, gsd_query, gsd_resolve_blocker
+ * Read-only tools (6): gsd_progress, gsd_roadmap, gsd_history, gsd_doctor, gsd_captures, gsd_knowledge
  *
  * Uses dynamic imports for @modelcontextprotocol/sdk because TS Node16
  * cannot resolve the SDK's subpath exports statically (same pattern as
@@ -10,6 +13,12 @@ import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
+import { readProgress } from './readers/state.js';
+import { readRoadmap } from './readers/roadmap.js';
+import { readHistory } from './readers/metrics.js';
+import { readCaptures } from './readers/captures.js';
+import { readKnowledge } from './readers/knowledge.js';
+import { runDoctorLite } from './readers/doctor-lite.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -17,7 +26,7 @@ import type { SessionManager } from './session-manager.js';
 
 const MCP_PKG = '@modelcontextprotocol/sdk';
 const SERVER_NAME = 'gsd';
-const SERVER_VERSION = '2.51.0';
+const SERVER_VERSION = '2.53.0';
 
 // ---------------------------------------------------------------------------
 // Tool result helpers
@@ -106,7 +115,7 @@ interface McpServerInstance {
 // ---------------------------------------------------------------------------
 
 /**
- * Create and configure an MCP server with 6 GSD orchestration tools.
+ * Create and configure an MCP server with 12 GSD tools (6 session + 6 read-only).
  *
  * Returns the McpServer instance — call `connect(transport)` to start serving.
  * Uses dynamic imports for the MCP SDK to avoid TS subpath resolution issues.
@@ -274,5 +283,127 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{
     },
   );
 
+  // =======================================================================
+  // READ-ONLY TOOLS — no session required, pure filesystem reads
+  // =======================================================================
+
+  // -----------------------------------------------------------------------
+  // gsd_progress — structured project progress metrics
+  // -----------------------------------------------------------------------
+  server.tool(
+    'gsd_progress',
+    'Get structured project progress: active milestone/slice/task, phase, completion counts, blockers, and next action. No session required — reads directly from .gsd/ on disk.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { projectDir } = args as { projectDir: string };
+      try {
+        return jsonContent(readProgress(projectDir));
+      } catch (err) {
+        return errorContent(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // gsd_roadmap — milestone/slice/task structure with status
+  // -----------------------------------------------------------------------
+  server.tool(
+    'gsd_roadmap',
+    'Get the full project roadmap structure: milestones with their slices, tasks, status, risk, and dependencies. Optionally filter to a single milestone. No session required.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+      milestoneId: z.string().optional().describe('Filter to a specific milestone (e.g. "M001")'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { projectDir, milestoneId } = args as { projectDir: string; milestoneId?: string };
+      try {
+        return jsonContent(readRoadmap(projectDir, milestoneId));
+      } catch (err) {
+        return errorContent(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // gsd_history — execution history with cost/token metrics
+  // -----------------------------------------------------------------------
+  server.tool(
+    'gsd_history',
+    'Get execution history with cost, token usage, model, and duration per unit. Returns totals across all units. No session required.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+      limit: z.number().optional().describe('Max entries to return (most recent first). Default: all.'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { projectDir, limit } = args as { projectDir: string; limit?: number };
+      try {
+        return jsonContent(readHistory(projectDir, limit));
+      } catch (err) {
+        return errorContent(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // gsd_doctor — lightweight structural health check
+  // -----------------------------------------------------------------------
+  server.tool(
+    'gsd_doctor',
+    'Run a lightweight structural health check on the .gsd/ directory. Checks for missing files, status inconsistencies, and orphaned state. No session required.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+      scope: z.string().optional().describe('Limit checks to a specific milestone (e.g. "M001")'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { projectDir, scope } = args as { projectDir: string; scope?: string };
+      try {
+        return jsonContent(runDoctorLite(projectDir, scope));
+      } catch (err) {
+        return errorContent(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // gsd_captures — pending captures and ideas
+  // -----------------------------------------------------------------------
+  server.tool(
+    'gsd_captures',
+    'Get captured ideas and thoughts from CAPTURES.md with triage status. Filter by pending, actionable, or all. No session required.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+      filter: z.enum(['all', 'pending', 'actionable']).optional().describe('Filter captures (default: "all")'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { projectDir, filter } = args as { projectDir: string; filter?: 'all' | 'pending' | 'actionable' };
+      try {
+        return jsonContent(readCaptures(projectDir, filter ?? 'all'));
+      } catch (err) {
+        return errorContent(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // gsd_knowledge — project knowledge base
+  // -----------------------------------------------------------------------
+  server.tool(
+    'gsd_knowledge',
+    'Get the project knowledge base: rules, patterns, and lessons learned accumulated during development. No session required.',
+    {
+      projectDir: z.string().describe('Absolute path to the project directory'),
+    },
+    async (args: Record<string, unknown>) => {
+      const { projectDir } = args as { projectDir: string };
+      try {
+        return jsonContent(readKnowledge(projectDir));
+      } catch (err) {
+        return errorContent(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
   return { server };
 }

package/packages/pi-ai/dist/utils/repair-tool-json.d.ts

@@ -22,15 +22,35 @@
  */
 export declare function hasYamlBulletLists(json: string): boolean;
 /**
- * Attempt to repair YAML-style bullet lists embedded in a JSON string.
+ * Detect whether a JSON string contains XML parameter tags
+ * (i.e. `<parameter name="X">value</parameter>`).
  *
- * Converts patterns like:
- *   "keyDecisions": - Used Web Notification API..., "keyFiles": - file1
+ * Some models mix XML tool-call syntax into JSON string values,
+ * producing hybrid output that fails JSON.parse.
  *
- * Into:
- *   "keyDecisions": ["Used Web Notification API..."], "keyFiles": ["file1"]
+ * @see https://github.com/gsd-build/gsd-2/issues/3403
+ */
+export declare function hasXmlParameterTags(json: string): boolean;
+/**
+ * Detect whether a JSON string contains truncated numeric values
+ * (e.g. `"exitCode": -,` or `"durationMs": ,`).
+ *
+ * Smaller models sometimes emit incomplete numbers when the value
+ * is cut off mid-generation.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/3464
+ */
+export declare function hasTruncatedNumbers(json: string): boolean;
+/**
+ * Attempt to repair malformed JSON in LLM tool-call arguments.
+ *
+ * Handles three categories of malformation:
+ *
+ * 1. **YAML bullet lists** (#2660): `"key": - item1\n  - item2` → `"key": ["item1", "item2"]`
+ * 2. **XML parameter tags** (#3403): `<parameter name="X">value</parameter>` → stripped to content
+ * 3. **Truncated numbers** (#3464): `"exitCode": -,` → `"exitCode": 0,`
  *
- * Returns the original string unchanged if no YAML patterns are detected
+ * Returns the original string unchanged if no patterns are detected
  * or if the repair itself would produce invalid JSON.
  */
 export declare function repairToolJson(json: string): string;