gsd-pi 2.74.0-dev.b741afb → 2.74.0-dev.ffbcc03

package/packages/mcp-server/src/readers/graph.test.ts

@@ -98,6 +98,49 @@ function makeProjectWithArtifacts(projectDir: string): void {
   ].join('\n'));
 }
 
+// ---------------------------------------------------------------------------
+// LEARNINGS.md fixture helpers
+// ---------------------------------------------------------------------------
+
+function writeLearningsFixture(projectDir: string, milestoneId: string, content: string): void {
+  writeFixture(projectDir, `.gsd/milestones/${milestoneId}/${milestoneId}-LEARNINGS.md`, content);
+}
+
+const SAMPLE_LEARNINGS = `---
+phase: "M001"
+phase_name: "User Auth"
+project: "my-project"
+generated: "2026-04-15T10:00:00Z"
+counts:
+  decisions: 2
+  lessons: 1
+  patterns: 1
+  surprises: 1
+missing_artifacts: []
+---
+
+# Learnings: User Auth
+
+## Decisions
+- Use JWT for stateless auth across services.
+  Source: M001-PLAN.md/Architecture
+
+- Store refresh tokens in HTTP-only cookies only.
+  Source: M001-PLAN.md/Security
+
+## Lessons
+- Integration tests need a real DB — mocks missed migration bugs.
+  Source: M001-SUMMARY.md/Testing
+
+## Patterns
+- Repository pattern abstracts DB access and simplifies testing.
+  Source: M001-PLAN.md/Design
+
+## Surprises
+- Token expiry edge case caused silent auth failures in prod.
+  Source: M001-SUMMARY.md/Issues
+`;
+
 // ---------------------------------------------------------------------------
 // buildGraph tests
 // ---------------------------------------------------------------------------
@@ -162,6 +205,141 @@ describe('buildGraph', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// buildGraph — LEARNINGS.md parsing tests
+// ---------------------------------------------------------------------------
+
+describe('buildGraph — LEARNINGS.md parsing', () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = tmpProject();
+    // Create minimal milestone directory so parseMilestoneFiles finds it
+    mkdirSync(join(projectDir, '.gsd', 'milestones', 'M001'), { recursive: true });
+    writeLearningsFixture(projectDir, 'M001', SAMPLE_LEARNINGS);
+  });
+
+  afterEach(() => rmSync(projectDir, { recursive: true, force: true }));
+
+  it('extracts decision nodes from ## Decisions section', async () => {
+    const graph = await buildGraph(projectDir);
+    const decisions = graph.nodes.filter((n) => n.type === 'decision' || (n.type === 'rule' && n.id.startsWith('decision:')));
+    // Decisions should be extracted with a 'decision' type (or similar existing type)
+    const decisionNodes = graph.nodes.filter((n) => n.id.includes('decision:M001'));
+    assert.ok(decisionNodes.length >= 2, `Expected >= 2 decision nodes, got ${decisionNodes.length}`);
+  });
+
+  it('extracts lesson nodes from ## Lessons section', async () => {
+    const graph = await buildGraph(projectDir);
+    const lessonNodes = graph.nodes.filter((n) => n.id.includes('lesson:M001'));
+    assert.ok(lessonNodes.length >= 1, `Expected >= 1 lesson node, got ${lessonNodes.length}`);
+    assert.ok(lessonNodes.every((n) => n.type === 'lesson'), 'All lesson nodes must have type "lesson"');
+  });
+
+  it('extracts pattern nodes from ## Patterns section', async () => {
+    const graph = await buildGraph(projectDir);
+    const patternNodes = graph.nodes.filter((n) => n.id.includes('pattern:M001'));
+    assert.ok(patternNodes.length >= 1, `Expected >= 1 pattern node, got ${patternNodes.length}`);
+    assert.ok(patternNodes.every((n) => n.type === 'pattern'), 'All pattern nodes must have type "pattern"');
+  });
+
+  it('maps surprises to lesson nodes', async () => {
+    const graph = await buildGraph(projectDir);
+    // Surprises should be mapped to lesson type since no "surprise" NodeType exists
+    const surpriseNodes = graph.nodes.filter((n) => n.id.includes('surprise:M001'));
+    assert.ok(surpriseNodes.length >= 1, `Expected >= 1 surprise node, got ${surpriseNodes.length}`);
+    assert.ok(surpriseNodes.every((n) => n.type === 'lesson'), 'Surprises must be mapped to type "lesson"');
+  });
+
+  it('node labels contain the learning text', async () => {
+    const graph = await buildGraph(projectDir);
+    const hasJwtDecision = graph.nodes.some((n) =>
+      n.label.toLowerCase().includes('jwt') || n.description?.toLowerCase().includes('jwt'),
+    );
+    assert.ok(hasJwtDecision, 'Expected a node describing the JWT decision');
+  });
+
+  it('node description includes source attribution', async () => {
+    const graph = await buildGraph(projectDir);
+    const learningNodes = graph.nodes.filter((n) =>
+      n.id.includes(':M001:') || n.id.match(/:(decision|lesson|pattern|surprise):M001/),
+    );
+    const withSource = learningNodes.filter((n) => n.description?.includes('Source:') || n.description?.includes('M001-PLAN'));
+    assert.ok(withSource.length > 0, 'Expected at least one node with source attribution in description');
+  });
+
+  it('adds relates_to edge from learning node to milestone node', async () => {
+    const graph = await buildGraph(projectDir);
+    const edgesToMilestone = graph.edges.filter(
+      (e) => e.to === 'milestone:M001' || e.from === 'milestone:M001',
+    );
+    // At least one learning node should relate to the milestone
+    const learningEdges = graph.edges.filter(
+      (e) => (e.from.includes('M001') && (e.type === 'relates_to' || e.type === 'contains')) ||
+              (e.to.includes('M001') && e.type === 'relates_to'),
+    );
+    assert.ok(learningEdges.length > 0 || edgesToMilestone.length > 0,
+      'Expected edges connecting learning nodes to milestone');
+  });
+
+  it('skips LEARNINGS.md gracefully when file is malformed', async () => {
+    const badProject = tmpProject();
+    mkdirSync(join(badProject, '.gsd', 'milestones', 'M002'), { recursive: true });
+    writeLearningsFixture(badProject, 'M002', '\0\0\0 not valid yaml or markdown \0\0\0');
+    // Must not throw
+    const graph = await buildGraph(badProject);
+    assert.ok(graph.nodes.length >= 0);
+    assert.equal(typeof graph.builtAt, 'string');
+    rmSync(badProject, { recursive: true, force: true });
+  });
+
+  it('produces no learning nodes when all sections are empty', async () => {
+    const emptyProject = tmpProject();
+    mkdirSync(join(emptyProject, '.gsd', 'milestones', 'M003'), { recursive: true });
+    writeLearningsFixture(emptyProject, 'M003', `---
+phase: "M003"
+phase_name: "Empty"
+project: "test"
+generated: "2026-04-15T10:00:00Z"
+counts:
+  decisions: 0
+  lessons: 0
+  patterns: 0
+  surprises: 0
+missing_artifacts: []
+---
+
+# Learnings: Empty
+
+## Decisions
+
+## Lessons
+
+## Patterns
+
+## Surprises
+`);
+    const graph = await buildGraph(emptyProject);
+    const learningNodes = graph.nodes.filter((n) =>
+      n.id.includes('decision:M003') ||
+      n.id.includes('lesson:M003') ||
+      n.id.includes('pattern:M003') ||
+      n.id.includes('surprise:M003'),
+    );
+    assert.equal(learningNodes.length, 0, 'Empty sections should produce no nodes');
+    rmSync(emptyProject, { recursive: true, force: true });
+  });
+
+  it('does not crash when LEARNINGS.md is missing entirely', async () => {
+    const noLearningsProject = tmpProject();
+    mkdirSync(join(noLearningsProject, '.gsd', 'milestones', 'M004'), { recursive: true });
+    // No LEARNINGS.md file written
+    const graph = await buildGraph(noLearningsProject);
+    assert.ok(graph.nodes.length >= 0);
+    rmSync(noLearningsProject, { recursive: true, force: true });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // writeGraph tests
 // ---------------------------------------------------------------------------

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

@@ -27,7 +27,8 @@ export type NodeType =
   | 'rule'
   | 'pattern'
   | 'lesson'
-  | 'concept';
+  | 'concept'
+  | 'decision';
 
 export type EdgeType =
   | 'contains'
@@ -386,6 +387,151 @@ function parseTasksFromPlan(
   }
 }
 
+// ---------------------------------------------------------------------------
+// LEARNINGS.md parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse all *-LEARNINGS.md files found in milestone directories.
+ * Extracts Decisions, Lessons, Patterns, and Surprises as typed graph nodes.
+ * Surprises are mapped to the 'lesson' NodeType (no distinct type exists).
+ * Parse errors per file are caught — the file is skipped, never rethrows.
+ */
+function parseLearningsFiles(gsdRoot: string, nodes: GraphNode[], edges: GraphEdge[]): void {
+  const milestoneIds = findMilestoneIds(gsdRoot);
+
+  for (const milestoneId of milestoneIds) {
+    try {
+      parseSingleLearningsFile(gsdRoot, milestoneId, nodes, edges);
+    } catch {
+      // Skip this milestone's LEARNINGS.md on any error
+    }
+  }
+}
+
+function parseSingleLearningsFile(
+  gsdRoot: string,
+  milestoneId: string,
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+): void {
+  const mDir = resolveMilestoneDir(gsdRoot, milestoneId);
+  if (!mDir) return;
+
+  const learningsPath = join(mDir, `${milestoneId}-LEARNINGS.md`);
+  if (!existsSync(learningsPath)) return;
+
+  let content: string;
+  try {
+    content = readFileSync(learningsPath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  // Strip YAML frontmatter if present
+  const withoutFrontmatter = content.replace(/^---[\s\S]*?---\n?/, '');
+
+  const milestoneNodeId = `milestone:${milestoneId}`;
+  const sourceFile = `milestones/${milestoneId}/${milestoneId}-LEARNINGS.md`;
+
+  // Parse each section: [sectionName, nodeType, idPrefix]
+  const sections: Array<[string, NodeType, string]> = [
+    ['Decisions', 'decision', 'decision'],
+    ['Lessons', 'lesson', 'lesson'],
+    ['Patterns', 'pattern', 'pattern'],
+    ['Surprises', 'lesson', 'surprise'],
+  ];
+
+  for (const [sectionName, nodeType, idPrefix] of sections) {
+    const sectionMatch = withoutFrontmatter.match(
+      new RegExp(`##\\s+${sectionName}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`, 'i'),
+    );
+    if (!sectionMatch) continue;
+
+    const sectionContent = sectionMatch[1];
+    parseLearningsSection(
+      sectionContent,
+      milestoneId,
+      idPrefix,
+      nodeType,
+      milestoneNodeId,
+      sourceFile,
+      nodes,
+      edges,
+    );
+  }
+}
+
+function parseLearningsSection(
+  sectionContent: string,
+  milestoneId: string,
+  idPrefix: string,
+  nodeType: NodeType,
+  milestoneNodeId: string,
+  sourceFile: string,
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+): void {
+  // Each item is a bullet line starting with "- " followed by optional
+  // indented "Source: ..." line.
+  // We collect bullet items and their associated source attribution.
+  const lines = sectionContent.split('\n');
+  let itemIndex = 0;
+  let currentText: string | null = null;
+  let currentSource: string | null = null;
+
+  const flushItem = (): void => {
+    if (!currentText) return;
+    itemIndex += 1;
+    const nodeId = `${idPrefix}:${milestoneId}:${itemIndex}`;
+    const description = currentSource ? `${currentSource}` : undefined;
+
+    nodes.push({
+      id: nodeId,
+      label: currentText,
+      type: nodeType,
+      description,
+      confidence: 'EXTRACTED',
+      sourceFile,
+    });
+
+    // Edge: milestone relates_to this learning node
+    edges.push({
+      from: milestoneNodeId,
+      to: nodeId,
+      type: 'relates_to',
+      confidence: 'EXTRACTED',
+    });
+
+    currentText = null;
+    currentSource = null;
+  };
+
+  for (const line of lines) {
+    const bulletMatch = line.match(/^[-*]\s+(.+)/);
+    if (bulletMatch) {
+      flushItem();
+      currentText = bulletMatch[1].trim();
+      continue;
+    }
+
+    // Indented source attribution: "  Source: ..."
+    const sourceMatch = line.match(/^\s+Source:\s+(.+)/i);
+    if (sourceMatch && currentText !== null) {
+      currentSource = `Source: ${sourceMatch[1].trim()}`;
+      continue;
+    }
+
+    // Continuation of current item text (indented non-source line)
+    const continuationMatch = line.match(/^\s{2,}(.+)/);
+    if (continuationMatch && currentText !== null && currentSource === null) {
+      currentText += ' ' + continuationMatch[1].trim();
+    }
+  }
+
+  flushItem();
+}
+
 // ---------------------------------------------------------------------------
 // buildGraph
 // ---------------------------------------------------------------------------
@@ -407,6 +553,7 @@ export async function buildGraph(projectDir: string): Promise<KnowledgeGraph> {
     parseStateFile,
     parseKnowledgeFile,
     parseMilestoneFiles,
+    parseLearningsFiles,
   ];
 
   for (const parser of parsers) {

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

@@ -2,7 +2,8 @@
  * Workflow MCP tools — exposes the core GSD mutation/read handlers over MCP.
  */
 
-import { isAbsolute, relative, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
 
@@ -262,6 +263,22 @@ function isWithinRoot(candidatePath: string, rootPath: string): boolean {
   return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
 
+/**
+ * Resolve the symlink target of `<allowedRoot>/.gsd` when it points into the
+ * external state layout (`~/.gsd/projects/<hash>/`). Returns the realpath of
+ * that target so callers can accept worktree paths that live under
+ * `<external-state>/worktrees/<MID>/`. Returns null when `.gsd` is absent or
+ * resolution fails — the caller should fall back to the direct containment
+ * check in that case.
+ */
+function resolveExternalStateRoot(allowedRoot: string): string | null {
+  try {
+    return realpathSync(join(allowedRoot, ".gsd"));
+  } catch {
+    return null;
+  }
+}
+
 function validateProjectDir(projectDir: string, env: NodeJS.ProcessEnv = process.env): string {
   if (!isAbsolute(projectDir)) {
     throw new Error(`projectDir must be an absolute path. Received: ${projectDir}`);
@@ -269,27 +286,88 @@ function validateProjectDir(projectDir: string, env: NodeJS.ProcessEnv = process
 
   const resolvedProjectDir = resolve(projectDir);
   const allowedRoot = getAllowedProjectRoot(env);
-  if (allowedRoot && !isWithinRoot(resolvedProjectDir, allowedRoot)) {
-    throw new Error(
-      `projectDir must stay within the configured workflow project root. Received: ${resolvedProjectDir}; allowed root: ${allowedRoot}`,
-    );
+  if (!allowedRoot) return resolvedProjectDir;
+
+  if (isWithinRoot(resolvedProjectDir, allowedRoot)) return resolvedProjectDir;
+
+  // External state layout: `<allowedRoot>/.gsd` may be a symlink into
+  // `~/.gsd/projects/<hash>/`, and auto-worktrees live under
+  // `~/.gsd/projects/<hash>/worktrees/<MID>/`. Accept candidates that are
+  // under the realpath of `<allowedRoot>/.gsd` — they belong to this project
+  // even though their absolute path is outside allowedRoot (#issue-a44).
+  const externalRoot = resolveExternalStateRoot(allowedRoot);
+  if (externalRoot && isWithinRoot(resolvedProjectDir, externalRoot)) {
+    return resolvedProjectDir;
   }
 
-  return resolvedProjectDir;
+  throw new Error(
+    `projectDir must stay within the configured workflow project root. Received: ${resolvedProjectDir}; allowed root: ${allowedRoot}`,
+  );
 }
 
 function parseToolArgs<T>(schema: z.ZodType<T>, args: Record<string, unknown>): T {
   return schema.parse(args);
 }
 
-function parseWorkflowArgs<T extends { projectDir: string }>(
+/**
+ * Extract a milestone ID from parsed tool args, trying common field names.
+ * Returns null when no field is present or the value is not a string.
+ */
+function extractMilestoneId(parsed: Record<string, unknown>): string | null {
+  const candidates = [parsed.milestoneId, parsed.milestone_id, parsed.mid];
+  for (const c of candidates) {
+    if (typeof c === "string" && c.trim() !== "") return c.trim();
+  }
+  return null;
+}
+
+/**
+ * If an auto-worktree exists for the given milestone under
+ * `<projectRoot>/.gsd/worktrees/<milestoneId>/`, return that path as the
+ * basePath the tool should write against. Returns null when no worktree
+ * exists for this milestone, leaving the caller to use the project root.
+ *
+ * This unbreaks the external-state layout where the MCP server's process.cwd()
+ * is the project root (set at Claude Code launch) but auto-mode is actually
+ * working inside a per-milestone worktree. Without this, tool writes go to
+ * the shared project `.gsd/` and auto-mode's verifyExpectedArtifact (which
+ * uses the worktree `.gsd/`) fails, triggering a guaranteed retry per unit.
+ */
+function resolveActiveWorktreeBasePath(
+  projectRoot: string,
+  milestoneId: string | null,
+): string | null {
+  if (!milestoneId) return null;
+  const wtPath = join(projectRoot, ".gsd", "worktrees", milestoneId);
+  if (!existsSync(wtPath)) return null;
+  // Sanity check: a real git worktree has a `.git` file with a gitdir pointer.
+  // Bare directories without it shouldn't hijack the write path.
+  if (!existsSync(join(wtPath, ".git"))) return null;
+  return wtPath;
+}
+
+function parseWorkflowArgs<T extends { projectDir?: string }>(
   schema: z.ZodType<T>,
   args: Record<string, unknown>,
-): T {
+): T & { projectDir: string } {
   const parsed = parseToolArgs(schema, args);
+  // Step 1: figure out the project root. The agent shouldn't need to pass
+  // projectDir — default to process.cwd() which the MCP server inherited from
+  // Claude Code (launched at the project root).
+  const projectRootCandidate = parsed.projectDir ?? process.cwd();
+  const projectRoot = validateProjectDir(projectRootCandidate);
+
+  // Step 2: if this tool call is scoped to a milestone that has an active
+  // auto-worktree, re-route writes to the worktree's .gsd rather than the
+  // project's shared .gsd. auto-mode's verifyExpectedArtifact runs against
+  // the worktree, and a mismatch here causes every unit to retry once.
+  const milestoneId = extractMilestoneId(parsed as Record<string, unknown>);
+  const worktreeBasePath = resolveActiveWorktreeBasePath(projectRoot, milestoneId);
+  const effectiveBasePath = worktreeBasePath ?? projectRoot;
+
   return {
     ...parsed,
-    projectDir: validateProjectDir(parsed.projectDir),
+    projectDir: effectiveBasePath,
   };
 }
 
@@ -664,7 +742,14 @@ async function ensureMilestoneDbRow(milestoneId: string): Promise<void> {
   }
 }
 
-const projectDirParam = z.string().describe("Absolute path to the project directory within the configured workflow root");
+// projectDir is optional. When omitted, the server uses process.cwd(). This
+// prevents the agent from burning tokens reasoning about which absolute path
+// to pass (git root vs worktree vs symlink-resolved external state layout) —
+// the server already knows where it is running.
+const projectDirParam = z
+  .string()
+  .optional()
+  .describe("Optional. Omit this field — the server defaults to its current working directory, which is already the correct project or worktree root.");
 
 const planMilestoneParams = {
   projectDir: projectDirParam,