gsd-pi 2.62.0-dev.f6ad485 → 2.62.1-dev.1ae2b74

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

@@ -15,7 +15,7 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
 async function main(): Promise<void> {
   const sessionManager = new SessionManager();
 
-  // Create the configured MCP server with all 6 tools
+  // Create the configured MCP server with all 12 tools (6 session + 6 read-only)
   const { server } = await createMcpServer(sessionManager);
 
   // Dynamic import for StdioServerTransport (same TS subpath workaround)

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

@@ -1,5 +1,5 @@
 /**
- * @gsd-build/mcp-server — MCP server for GSD orchestration.
+ * @gsd-build/mcp-server — MCP server for GSD orchestration and project state.
  */
 
 export { SessionManager } from './session-manager.js';
@@ -12,3 +12,17 @@ export type {
   CostAccumulator,
 } from './types.js';
 export { MAX_EVENTS, INIT_TIMEOUT_MS } from './types.js';
+
+// Read-only state readers (usable without a running session)
+export { readProgress } from './readers/state.js';
+export type { ProgressResult } from './readers/state.js';
+export { readRoadmap } from './readers/roadmap.js';
+export type { RoadmapResult, MilestoneInfo, SliceInfo, TaskInfo } from './readers/roadmap.js';
+export { readHistory } from './readers/metrics.js';
+export type { HistoryResult, MetricsUnit } from './readers/metrics.js';
+export { readCaptures } from './readers/captures.js';
+export type { CapturesResult, CaptureEntry } from './readers/captures.js';
+export { readKnowledge } from './readers/knowledge.js';
+export type { KnowledgeResult, KnowledgeEntry } from './readers/knowledge.js';
+export { runDoctorLite } from './readers/doctor-lite.js';
+export type { DoctorResult, DoctorIssue } from './readers/doctor-lite.js';

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

@@ -0,0 +1,119 @@
+// GSD MCP Server — captures reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveGsdRoot, resolveRootFile } from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type CaptureStatus = 'pending' | 'triaged' | 'resolved';
+export type CaptureClassification =
+  | 'quick-task' | 'inject' | 'defer' | 'replan' | 'note' | 'stop' | 'backtrack';
+
+export interface CaptureEntry {
+  id: string;
+  text: string;
+  timestamp: string;
+  status: CaptureStatus;
+  classification: CaptureClassification | null;
+  resolution: string | null;
+  rationale: string | null;
+  resolvedAt: string | null;
+  milestone: string | null;
+  executed: string | null;
+}
+
+export interface CapturesResult {
+  captures: CaptureEntry[];
+  counts: {
+    total: number;
+    pending: number;
+    resolved: number;
+    actionable: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+function parseCapturesMarkdown(content: string): CaptureEntry[] {
+  const entries: CaptureEntry[] = [];
+
+  // Split on H3 headers: ### CAP-xxxxxxxx
+  const sections = content.split(/(?=^### CAP-)/m);
+
+  for (const section of sections) {
+    const idMatch = section.match(/^### (CAP-[\da-f]+)/);
+    if (!idMatch) continue;
+
+    const id = idMatch[1];
+    const field = (label: string): string | null => {
+      const re = new RegExp(`\\*\\*${label}:\\*\\*\\s*(.+)`, 'i');
+      const m = section.match(re);
+      return m ? m[1].trim() : null;
+    };
+
+    const status = (field('Status') ?? 'pending').toLowerCase() as CaptureStatus;
+    const classification = field('Classification') as CaptureClassification | null;
+
+    entries.push({
+      id,
+      text: field('Text') ?? '',
+      timestamp: field('Captured') ?? '',
+      status,
+      classification,
+      resolution: field('Resolution'),
+      rationale: field('Rationale'),
+      resolvedAt: field('Resolved'),
+      milestone: field('Milestone'),
+      executed: field('Executed'),
+    });
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const ACTIONABLE_CLASSIFICATIONS = new Set<string>(['quick-task', 'inject', 'replan']);
+
+export function readCaptures(
+  projectDir: string,
+  filter: 'all' | 'pending' | 'actionable' = 'all',
+): CapturesResult {
+  const gsd = resolveGsdRoot(projectDir);
+  const capturesPath = resolveRootFile(gsd, 'CAPTURES.md');
+
+  if (!existsSync(capturesPath)) {
+    return { captures: [], counts: { total: 0, pending: 0, resolved: 0, actionable: 0 } };
+  }
+
+  const content = readFileSync(capturesPath, 'utf-8');
+  let captures = parseCapturesMarkdown(content);
+
+  // Compute counts before filtering
+  const counts = {
+    total: captures.length,
+    pending: captures.filter((c) => c.status === 'pending').length,
+    resolved: captures.filter((c) => c.status === 'resolved').length,
+    actionable: captures.filter(
+      (c) => c.classification !== null && ACTIONABLE_CLASSIFICATIONS.has(c.classification),
+    ).length,
+  };
+
+  // Apply filter
+  if (filter === 'pending') {
+    captures = captures.filter((c) => c.status === 'pending');
+  } else if (filter === 'actionable') {
+    captures = captures.filter(
+      (c) => c.classification !== null && ACTIONABLE_CLASSIFICATIONS.has(c.classification),
+    );
+  }
+
+  return { captures, counts };
+}

package/packages/mcp-server/src/readers/doctor-lite.ts

@@ -0,0 +1,225 @@
+// GSD MCP Server — lightweight structural health checks
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  resolveGsdRoot,
+  resolveRootFile,
+  findMilestoneIds,
+  resolveMilestoneFile,
+  resolveMilestoneDir,
+  findSliceIds,
+  resolveSliceFile,
+  findTaskFiles,
+} from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Severity = 'info' | 'warning' | 'error';
+
+export interface DoctorIssue {
+  severity: Severity;
+  code: string;
+  scope: 'project' | 'milestone' | 'slice' | 'task';
+  unitId: string;
+  message: string;
+  file?: string;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  issues: DoctorIssue[];
+  counts: { error: number; warning: number; info: number };
+}
+
+// ---------------------------------------------------------------------------
+// Check implementations
+// ---------------------------------------------------------------------------
+
+function checkProjectLevel(gsdRoot: string, issues: DoctorIssue[]): void {
+  // PROJECT.md should exist
+  const projectPath = resolveRootFile(gsdRoot, 'PROJECT.md');
+  if (!existsSync(projectPath)) {
+    issues.push({
+      severity: 'warning',
+      code: 'missing_project_md',
+      scope: 'project',
+      unitId: '',
+      message: 'PROJECT.md is missing — project lacks a description',
+      file: projectPath,
+    });
+  }
+
+  // STATE.md should exist if milestones exist
+  const milestones = findMilestoneIds(gsdRoot);
+  if (milestones.length > 0) {
+    const statePath = resolveRootFile(gsdRoot, 'STATE.md');
+    if (!existsSync(statePath)) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_state_md',
+        scope: 'project',
+        unitId: '',
+        message: 'STATE.md is missing — run /gsd status to regenerate',
+        file: statePath,
+      });
+    }
+  }
+}
+
+function checkMilestoneLevel(gsdRoot: string, mid: string, issues: DoctorIssue[]): void {
+  const mDir = resolveMilestoneDir(gsdRoot, mid);
+  if (!mDir) {
+    issues.push({
+      severity: 'error',
+      code: 'missing_milestone_dir',
+      scope: 'milestone',
+      unitId: mid,
+      message: `Milestone directory for ${mid} not found`,
+    });
+    return;
+  }
+
+  // CONTEXT.md should exist
+  const ctxPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT');
+  if (!ctxPath || !existsSync(ctxPath)) {
+    // Check for draft
+    const draftPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT-DRAFT');
+    if (!draftPath || !existsSync(draftPath)) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_context',
+        scope: 'milestone',
+        unitId: mid,
+        message: `${mid} has no CONTEXT.md — milestone lacks defined scope`,
+      });
+    }
+  }
+
+  // ROADMAP.md should exist if slices exist
+  const sliceIds = findSliceIds(gsdRoot, mid);
+  if (sliceIds.length > 0) {
+    const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP');
+    if (!roadmapPath || !existsSync(roadmapPath)) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_roadmap',
+        scope: 'milestone',
+        unitId: mid,
+        message: `${mid} has ${sliceIds.length} slices but no ROADMAP.md`,
+      });
+    }
+  }
+
+  // Check if all slices done but no SUMMARY
+  if (sliceIds.length > 0) {
+    const allDone = sliceIds.every((sid) => {
+      const tasks = findTaskFiles(gsdRoot, mid, sid);
+      return tasks.length > 0 && tasks.every((t) => t.hasSummary);
+    });
+    const summaryPath = resolveMilestoneFile(gsdRoot, mid, 'SUMMARY');
+    if (allDone && (!summaryPath || !existsSync(summaryPath))) {
+      issues.push({
+        severity: 'error',
+        code: 'all_slices_done_missing_summary',
+        scope: 'milestone',
+        unitId: mid,
+        message: `${mid} has all slices completed but no SUMMARY.md`,
+      });
+    }
+  }
+}
+
+function checkSliceLevel(
+  gsdRoot: string, mid: string, sid: string, issues: DoctorIssue[],
+): void {
+  const unitId = `${mid}/${sid}`;
+
+  // PLAN.md should exist
+  const planPath = resolveSliceFile(gsdRoot, mid, sid, 'PLAN');
+  if (!planPath || !existsSync(planPath)) {
+    issues.push({
+      severity: 'error',
+      code: 'missing_slice_plan',
+      scope: 'slice',
+      unitId,
+      message: `${unitId} has no PLAN.md`,
+    });
+  }
+
+  // Tasks should have plans
+  const tasks = findTaskFiles(gsdRoot, mid, sid);
+  for (const task of tasks) {
+    const taskUnitId = `${unitId}/${task.id}`;
+    if (!task.hasPlan) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_task_plan',
+        scope: 'task',
+        unitId: taskUnitId,
+        message: `${taskUnitId} has a summary but no plan file`,
+      });
+    }
+  }
+
+  // Check for empty slice (directory exists but no tasks or plan)
+  if (tasks.length === 0 && (!planPath || !existsSync(planPath))) {
+    issues.push({
+      severity: 'warning',
+      code: 'empty_slice',
+      scope: 'slice',
+      unitId,
+      message: `${unitId} has no plan and no tasks — may be abandoned`,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function runDoctorLite(projectDir: string, scope?: string): DoctorResult {
+  const gsdRoot = resolveGsdRoot(projectDir);
+  const issues: DoctorIssue[] = [];
+
+  if (!existsSync(gsdRoot)) {
+    return {
+      ok: true,
+      issues: [{
+        severity: 'info',
+        code: 'no_gsd_directory',
+        scope: 'project',
+        unitId: '',
+        message: 'No .gsd/ directory found — project not initialized',
+      }],
+      counts: { error: 0, warning: 0, info: 1 },
+    };
+  }
+
+  // Project-level checks
+  checkProjectLevel(gsdRoot, issues);
+
+  // Milestone + slice checks
+  const milestoneIds = scope
+    ? findMilestoneIds(gsdRoot).filter((id) => id === scope)
+    : findMilestoneIds(gsdRoot);
+
+  for (const mid of milestoneIds) {
+    checkMilestoneLevel(gsdRoot, mid, issues);
+
+    const sliceIds = findSliceIds(gsdRoot, mid);
+    for (const sid of sliceIds) {
+      checkSliceLevel(gsdRoot, mid, sid, issues);
+    }
+  }
+
+  const counts = {
+    error: issues.filter((i) => i.severity === 'error').length,
+    warning: issues.filter((i) => i.severity === 'warning').length,
+    info: issues.filter((i) => i.severity === 'info').length,
+  };
+
+  return { ok: counts.error === 0, issues, counts };
+}

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

@@ -0,0 +1,16 @@
+// GSD MCP Server — readers barrel export
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+export { resolveGsdRoot, resolveRootFile } from './paths.js';
+export { readProgress } from './state.js';
+export type { ProgressResult } from './state.js';
+export { readRoadmap } from './roadmap.js';
+export type { RoadmapResult, MilestoneInfo, SliceInfo, TaskInfo } from './roadmap.js';
+export { readHistory } from './metrics.js';
+export type { HistoryResult, MetricsUnit } from './metrics.js';
+export { readCaptures } from './captures.js';
+export type { CapturesResult, CaptureEntry } from './captures.js';
+export { readKnowledge } from './knowledge.js';
+export type { KnowledgeResult, KnowledgeEntry } from './knowledge.js';
+export { runDoctorLite } from './doctor-lite.js';
+export type { DoctorResult, DoctorIssue } from './doctor-lite.js';

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

@@ -0,0 +1,111 @@
+// GSD MCP Server — knowledge base reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveGsdRoot, resolveRootFile } from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type KnowledgeType = 'rule' | 'pattern' | 'lesson';
+
+export interface KnowledgeEntry {
+  id: string;
+  type: KnowledgeType;
+  scope: string;
+  content: string;
+  addedAt: string;
+}
+
+export interface KnowledgeResult {
+  entries: KnowledgeEntry[];
+  counts: { rules: number; patterns: number; lessons: number };
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+function parseTableRows(section: string, type: KnowledgeType): KnowledgeEntry[] {
+  const entries: KnowledgeEntry[] = [];
+  const lines = section.split('\n');
+
+  for (const line of lines) {
+    if (!line.includes('|')) continue;
+    const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
+    if (cells.length < 3) continue;
+    // Skip header/separator
+    if (cells[0].startsWith('#') || cells[0].startsWith('-')) continue;
+
+    const id = cells[0];
+    if (!/^[KPL]\d+$/i.test(id)) continue;
+
+    if (type === 'rule' && cells.length >= 5) {
+      entries.push({
+        id, type, scope: cells[1], content: cells[2], addedAt: cells[4] ?? '',
+      });
+    } else if (type === 'pattern' && cells.length >= 4) {
+      entries.push({
+        id, type, scope: cells[2] ?? '', content: cells[1], addedAt: cells[3] ?? '',
+      });
+    } else if (type === 'lesson' && cells.length >= 5) {
+      entries.push({
+        id, type, scope: cells[4] ?? '',
+        content: `${cells[1]} — Root cause: ${cells[2]} — Fix: ${cells[3]}`,
+        addedAt: '',
+      });
+    }
+  }
+
+  return entries;
+}
+
+function parseKnowledgeMarkdown(content: string): KnowledgeEntry[] {
+  const entries: KnowledgeEntry[] = [];
+
+  // Find ## Rules section
+  const rulesMatch = content.match(/## Rules\s*\n([\s\S]*?)(?=\n## |$)/i);
+  if (rulesMatch) {
+    entries.push(...parseTableRows(rulesMatch[1], 'rule'));
+  }
+
+  // Find ## Patterns section
+  const patternsMatch = content.match(/## Patterns\s*\n([\s\S]*?)(?=\n## |$)/i);
+  if (patternsMatch) {
+    entries.push(...parseTableRows(patternsMatch[1], 'pattern'));
+  }
+
+  // Find ## Lessons Learned section
+  const lessonsMatch = content.match(/## Lessons Learned\s*\n([\s\S]*?)(?=\n## |$)/i);
+  if (lessonsMatch) {
+    entries.push(...parseTableRows(lessonsMatch[1], 'lesson'));
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function readKnowledge(projectDir: string): KnowledgeResult {
+  const gsd = resolveGsdRoot(projectDir);
+  const knowledgePath = resolveRootFile(gsd, 'KNOWLEDGE.md');
+
+  if (!existsSync(knowledgePath)) {
+    return { entries: [], counts: { rules: 0, patterns: 0, lessons: 0 } };
+  }
+
+  const content = readFileSync(knowledgePath, 'utf-8');
+  const entries = parseKnowledgeMarkdown(content);
+
+  return {
+    entries,
+    counts: {
+      rules: entries.filter((e) => e.type === 'rule').length,
+      patterns: entries.filter((e) => e.type === 'pattern').length,
+      lessons: entries.filter((e) => e.type === 'lesson').length,
+    },
+  };
+}

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

@@ -0,0 +1,118 @@
+// GSD MCP Server — metrics/history reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveGsdRoot, resolveRootFile } from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface MetricsUnit {
+  type: string;
+  id: string;
+  model: string;
+  startedAt: number;
+  finishedAt: number;
+  tokens: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+  cost: number;
+  toolCalls: number;
+  apiRequests: number;
+}
+
+export interface HistoryResult {
+  entries: MetricsUnit[];
+  totals: {
+    cost: number;
+    tokens: { input: number; output: number; total: number };
+    units: number;
+    durationMs: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+function parseMetricsJson(content: string): MetricsUnit[] {
+  try {
+    const data = JSON.parse(content);
+    if (!data.units || !Array.isArray(data.units)) return [];
+
+    return data.units.map((u: Record<string, unknown>) => ({
+      type: String(u.type ?? 'unknown'),
+      id: String(u.id ?? ''),
+      model: String(u.model ?? 'unknown'),
+      startedAt: Number(u.startedAt ?? 0),
+      finishedAt: Number(u.finishedAt ?? 0),
+      tokens: {
+        input: Number((u.tokens as Record<string, unknown>)?.input ?? 0),
+        output: Number((u.tokens as Record<string, unknown>)?.output ?? 0),
+        cacheRead: Number((u.tokens as Record<string, unknown>)?.cacheRead ?? 0),
+        cacheWrite: Number((u.tokens as Record<string, unknown>)?.cacheWrite ?? 0),
+        total: Number((u.tokens as Record<string, unknown>)?.total ?? 0),
+      },
+      cost: Number(u.cost ?? 0),
+      toolCalls: Number(u.toolCalls ?? 0),
+      apiRequests: Number(u.apiRequests ?? 0),
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function readHistory(projectDir: string, limit?: number): HistoryResult {
+  const gsd = resolveGsdRoot(projectDir);
+
+  // metrics.json (primary)
+  const metricsPath = resolveRootFile(gsd, 'metrics.json');
+  let units: MetricsUnit[] = [];
+
+  if (existsSync(metricsPath)) {
+    const content = readFileSync(metricsPath, 'utf-8');
+    units = parseMetricsJson(content);
+  }
+
+  // Sort by startedAt descending (most recent first)
+  units.sort((a, b) => b.startedAt - a.startedAt);
+
+  // Apply limit
+  if (limit && limit > 0) {
+    units = units.slice(0, limit);
+  }
+
+  // Compute totals from ALL units (not just limited set)
+  const allUnits = existsSync(metricsPath)
+    ? parseMetricsJson(readFileSync(metricsPath, 'utf-8'))
+    : [];
+
+  const totals = {
+    cost: 0,
+    tokens: { input: 0, output: 0, total: 0 },
+    units: allUnits.length,
+    durationMs: 0,
+  };
+
+  for (const u of allUnits) {
+    totals.cost += u.cost;
+    totals.tokens.input += u.tokens.input;
+    totals.tokens.output += u.tokens.output;
+    totals.tokens.total += u.tokens.total;
+    totals.durationMs += (u.finishedAt - u.startedAt);
+  }
+
+  // Round cost to 4 decimal places
+  totals.cost = Math.round(totals.cost * 10000) / 10000;
+
+  return { entries: units, totals };
+}