gsd-remix 1.0.0

package/sdk/src/context-engine.ts

@@ -0,0 +1,170 @@
+/**
+ * Context engine — resolves which .planning/ state files exist per phase type.
+ *
+ * Different phases need different subsets of context files. The execute phase
+ * only needs STATE.md + config.json (minimal). Research needs STATE.md +
+ * ROADMAP.md + CONTEXT.md. Plan needs all files. Verify needs STATE.md +
+ * ROADMAP.md + REQUIREMENTS.md + PLAN/SUMMARY files.
+ *
+ * Context reduction (issue #1614):
+ * - Large files are truncated to keep prompts cache-friendly
+ * - ROADMAP.md is narrowed to the current milestone when possible
+ * - Truncation preserves headings + first paragraph per section
+ */
+
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { constants } from 'node:fs';
+
+import type { ContextFiles } from './types.js';
+import { PhaseType } from './types.js';
+import type { GSDLogger } from './logger.js';
+import {
+  truncateMarkdown,
+  extractCurrentMilestone,
+  DEFAULT_TRUNCATION_OPTIONS,
+  type TruncationOptions,
+} from './context-truncation.js';
+import { relPlanningPath } from './workstream-utils.js';
+
+// ─── File manifest per phase ─────────────────────────────────────────────────
+
+interface FileSpec {
+  key: keyof ContextFiles;
+  filename: string;
+  required: boolean;
+}
+
+/**
+ * Define which files each phase needs. Required files emit warnings when missing;
+ * optional files silently return undefined.
+ */
+const PHASE_FILE_MANIFEST: Record<PhaseType, FileSpec[]> = {
+  [PhaseType.Execute]: [
+    { key: 'state', filename: 'STATE.md', required: true },
+    { key: 'config', filename: 'config.json', required: false },
+  ],
+  [PhaseType.Research]: [
+    { key: 'state', filename: 'STATE.md', required: true },
+    { key: 'roadmap', filename: 'ROADMAP.md', required: true },
+    { key: 'context', filename: 'CONTEXT.md', required: true },
+    { key: 'requirements', filename: 'REQUIREMENTS.md', required: false },
+  ],
+  [PhaseType.Plan]: [
+    { key: 'state', filename: 'STATE.md', required: true },
+    { key: 'roadmap', filename: 'ROADMAP.md', required: true },
+    { key: 'context', filename: 'CONTEXT.md', required: true },
+    { key: 'research', filename: 'RESEARCH.md', required: false },
+    { key: 'requirements', filename: 'REQUIREMENTS.md', required: false },
+  ],
+  [PhaseType.Verify]: [
+    { key: 'state', filename: 'STATE.md', required: true },
+    { key: 'roadmap', filename: 'ROADMAP.md', required: true },
+    { key: 'requirements', filename: 'REQUIREMENTS.md', required: false },
+    { key: 'plan', filename: 'PLAN.md', required: false },
+    { key: 'summary', filename: 'SUMMARY.md', required: false },
+  ],
+  [PhaseType.Repair]: [
+    { key: 'state', filename: 'STATE.md', required: true },
+    { key: 'config', filename: 'config.json', required: false },
+    { key: 'plan', filename: 'PLAN.md', required: false },
+  ],
+  [PhaseType.Discuss]: [
+    { key: 'state', filename: 'STATE.md', required: true },
+    { key: 'roadmap', filename: 'ROADMAP.md', required: false },
+    { key: 'context', filename: 'CONTEXT.md', required: false },
+  ],
+};
+
+// ─── ContextEngine class ─────────────────────────────────────────────────────
+
+export class ContextEngine {
+  private readonly planningDir: string;
+  private readonly logger?: GSDLogger;
+  private readonly truncation: TruncationOptions;
+
+  constructor(projectDir: string, logger?: GSDLogger, truncation?: Partial<TruncationOptions>, workstream?: string) {
+    this.planningDir = join(projectDir, relPlanningPath(workstream));
+    this.logger = logger;
+    this.truncation = { ...DEFAULT_TRUNCATION_OPTIONS, ...truncation };
+  }
+
+  /**
+   * Resolve context files appropriate for the given phase type.
+   * Reads each file defined in the phase manifest, returning undefined
+   * for missing optional files and warning for missing required files.
+   *
+   * Files exceeding the truncation threshold are reduced to headings +
+   * first paragraphs. ROADMAP.md is narrowed to the current milestone.
+   */
+  async resolveContextFiles(phaseType: PhaseType): Promise<ContextFiles> {
+    const manifest = PHASE_FILE_MANIFEST[phaseType];
+    const result: ContextFiles = {};
+
+    for (const spec of manifest) {
+      const filePath = join(this.planningDir, spec.filename);
+      const content = await this.readFileIfExists(filePath);
+
+      if (content !== undefined) {
+        result[spec.key] = content;
+      } else if (spec.required) {
+        this.logger?.warn(`Required context file missing for ${phaseType} phase: ${spec.filename}`, {
+          phase: phaseType,
+          file: spec.filename,
+          path: filePath,
+        });
+      }
+    }
+
+    // Apply context reduction: milestone extraction then truncation
+    if (result.roadmap && result.state) {
+      const before = result.roadmap.length;
+      result.roadmap = extractCurrentMilestone(result.roadmap, result.state);
+      if (result.roadmap.length < before) {
+        this.logger?.debug?.('ROADMAP.md narrowed to current milestone', {
+          before,
+          after: result.roadmap.length,
+        });
+      }
+    }
+
+    // Truncate oversized files (skip config.json — structured data, not markdown)
+    const truncatable: Array<{ key: keyof ContextFiles; filename: string }> = [
+      { key: 'roadmap', filename: 'ROADMAP.md' },
+      { key: 'context', filename: 'CONTEXT.md' },
+      { key: 'research', filename: 'RESEARCH.md' },
+      { key: 'requirements', filename: 'REQUIREMENTS.md' },
+      { key: 'plan', filename: 'PLAN.md' },
+      { key: 'summary', filename: 'SUMMARY.md' },
+    ];
+
+    for (const { key, filename } of truncatable) {
+      const raw = result[key];
+      if (raw && raw.length > this.truncation.maxContentLength) {
+        const before = raw.length;
+        result[key] = truncateMarkdown(raw, filename, this.truncation);
+        this.logger?.debug?.(`${filename} truncated`, {
+          before,
+          after: result[key]!.length,
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check if a file exists and read it. Returns undefined if not found.
+   */
+  private async readFileIfExists(filePath: string): Promise<string | undefined> {
+    try {
+      await access(filePath, constants.R_OK);
+      return await readFile(filePath, 'utf-8');
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+export { PHASE_FILE_MANIFEST };
+export type { FileSpec };

package/sdk/src/context-truncation.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import {
+  truncateMarkdown,
+  extractCurrentMilestone,
+  DEFAULT_TRUNCATION_OPTIONS,
+} from './context-truncation.js';
+
+// ─── truncateMarkdown ───────────────────────────────────────────────────────
+
+describe('truncateMarkdown', () => {
+  it('returns content unchanged when below threshold', () => {
+    const content = '# Title\n\nShort content.';
+    const result = truncateMarkdown(content, 'TEST.md');
+    expect(result).toBe(content);
+  });
+
+  it('truncates content above threshold, keeping headings and first paragraphs', () => {
+    const sections = [];
+    for (let i = 0; i < 20; i++) {
+      sections.push(`## Section ${i}\n\nFirst paragraph of section ${i}.\n\nSecond paragraph with lots of detail.\nMore detail here.\nEven more detail.`);
+    }
+    const content = `# Title\n\n${sections.join('\n\n')}`;
+    const result = truncateMarkdown(content, 'BIG.md', { maxContentLength: 100 });
+
+    // Headings preserved
+    expect(result).toContain('# Title');
+    expect(result).toContain('## Section 0');
+    expect(result).toContain('## Section 19');
+
+    // First paragraphs preserved
+    expect(result).toContain('First paragraph of section 0.');
+    expect(result).toContain('First paragraph of section 19.');
+
+    // Second paragraphs omitted
+    expect(result).not.toContain('Second paragraph');
+    expect(result).not.toContain('More detail here.');
+
+    // Truncation markers present
+    expect(result).toContain('[...');
+    expect(result).toContain('lines omitted]');
+    expect(result).toContain('[Truncated: read .planning/BIG.md for full content]');
+  });
+
+  it('preserves YAML frontmatter entirely', () => {
+    const content = `---\nphase: "01"\nstatus: active\n---\n\n# Title\n\nParagraph 1.\n\nParagraph 2.\n${'x'.repeat(10000)}`;
+    const result = truncateMarkdown(content, 'STATE.md', { maxContentLength: 100 });
+
+    expect(result).toContain('---\nphase: "01"\nstatus: active\n---');
+    expect(result).toContain('# Title');
+    expect(result).toContain('Paragraph 1.');
+  });
+
+  it('is smaller than original when truncated', () => {
+    const longContent = Array.from({ length: 200 }, (_, i) =>
+      `## Section ${i}\n\nFirst paragraph.\n\nLong detail paragraph ${'x'.repeat(100)}.`
+    ).join('\n\n');
+
+    const result = truncateMarkdown(longContent, 'HUGE.md', { maxContentLength: 100 });
+    expect(result.length).toBeLessThan(longContent.length);
+  });
+
+  it('handles content with no headings', () => {
+    const content = `First line.\n\nSecond paragraph.\n\nThird paragraph.\n${'x'.repeat(10000)}`;
+    const result = truncateMarkdown(content, 'FLAT.md', { maxContentLength: 100 });
+
+    // Should still truncate — first paragraph kept
+    expect(result).toContain('First line.');
+    expect(result.length).toBeLessThan(content.length);
+  });
+
+  it('default threshold is 8192 characters', () => {
+    expect(DEFAULT_TRUNCATION_OPTIONS.maxContentLength).toBe(8192);
+  });
+});
+
+// ─── extractCurrentMilestone ────────────────────────────────────────────────
+
+describe('extractCurrentMilestone', () => {
+  const makeRoadmap = () => `# Project Roadmap
+
+## Milestone 1: Foundation
+### Phase 01: Setup
+Requirements for setup.
+### Phase 02: Core
+Requirements for core.
+
+## Milestone 2: Features
+### Phase 03: Auth
+Requirements for auth.
+### Phase 04: API
+Requirements for API.
+
+## Milestone 3: Polish
+### Phase 05: UI
+Requirements for UI.`;
+
+  it('returns full roadmap when no state provided', () => {
+    const roadmap = makeRoadmap();
+    expect(extractCurrentMilestone(roadmap)).toBe(roadmap);
+  });
+
+  it('returns full roadmap when milestone not found in state', () => {
+    const roadmap = makeRoadmap();
+    const state = '# State\nstatus: active';
+    expect(extractCurrentMilestone(roadmap, state)).toBe(roadmap);
+  });
+
+  it('extracts current milestone section by name', () => {
+    const roadmap = makeRoadmap();
+    const state = 'Current Milestone: Features';
+    const result = extractCurrentMilestone(roadmap, state);
+
+    expect(result).toContain('## Milestone 2: Features');
+    expect(result).toContain('### Phase 03: Auth');
+    expect(result).toContain('### Phase 04: API');
+
+    // Other milestones omitted
+    expect(result).not.toContain('### Phase 01: Setup');
+    expect(result).not.toContain('### Phase 05: UI');
+    expect(result).toContain('other milestone(s) omitted');
+  });
+
+  it('matches milestone name case-insensitively', () => {
+    const roadmap = makeRoadmap();
+    const state = 'current milestone: features';
+    const result = extractCurrentMilestone(roadmap, state);
+
+    expect(result).toContain('## Milestone 2: Features');
+    expect(result).not.toContain('### Phase 01: Setup');
+  });
+
+  it('matches milestone from "milestone:" field in state', () => {
+    const roadmap = makeRoadmap();
+    const state = '# State\nmilestone: Foundation\nphase: 01';
+    const result = extractCurrentMilestone(roadmap, state);
+
+    expect(result).toContain('## Milestone 1: Foundation');
+    expect(result).toContain('### Phase 01: Setup');
+    expect(result).not.toContain('### Phase 03: Auth');
+  });
+
+  it('matches milestone from Current Position block', () => {
+    const roadmap = makeRoadmap();
+    const state = `# State
+
+## Current Position
+milestone: Polish
+phase: 05`;
+    const result = extractCurrentMilestone(roadmap, state);
+
+    expect(result).toContain('## Milestone 3: Polish');
+    expect(result).toContain('### Phase 05: UI');
+    expect(result).not.toContain('### Phase 01: Setup');
+  });
+
+  it('preserves roadmap title in output', () => {
+    const roadmap = makeRoadmap();
+    const state = 'Current Milestone: Features';
+    const result = extractCurrentMilestone(roadmap, state);
+
+    expect(result).toContain('# Project Roadmap');
+  });
+});

package/sdk/src/context-truncation.ts

@@ -0,0 +1,233 @@
+/**
+ * Context truncation — reduces large .planning/ files to cache-friendly sizes.
+ *
+ * Two strategies:
+ * 1. Markdown-aware truncation: keeps headings + first paragraph per section,
+ *    replaces the rest with a pointer to the full file.
+ * 2. Milestone extraction: pulls only the current milestone from ROADMAP.md.
+ *
+ * All functions are pure — no I/O, no side effects.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface TruncationOptions {
+  /** Max content length in characters before truncation kicks in. Default: 8192 */
+  maxContentLength: number;
+}
+
+export const DEFAULT_TRUNCATION_OPTIONS: TruncationOptions = {
+  maxContentLength: 8192,
+};
+
+// ─── Markdown-aware truncation ──────────────────────────────────────────────
+
+/**
+ * Truncate markdown content while preserving structure.
+ *
+ * Strategy: keep YAML frontmatter, all headings, and the first paragraph under
+ * each heading. Collapse everything else with a line count summary.
+ *
+ * Returns the original content unchanged if below maxContentLength.
+ */
+export function truncateMarkdown(
+  content: string,
+  filename: string,
+  options: TruncationOptions = DEFAULT_TRUNCATION_OPTIONS,
+): string {
+  if (content.length <= options.maxContentLength) return content;
+
+  const lines = content.split('\n');
+  const kept: string[] = [];
+  let inFrontmatter = false;
+  let frontmatterDone = false;
+  let currentSectionLines = 0;
+  let paragraphKept = false;
+  let omittedLines = 0;
+  let inParagraph = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Handle YAML frontmatter (preserve entirely)
+    if (i === 0 && line.trim() === '---') {
+      inFrontmatter = true;
+      kept.push(line);
+      continue;
+    }
+    if (inFrontmatter) {
+      kept.push(line);
+      if (line.trim() === '---') {
+        inFrontmatter = false;
+        frontmatterDone = true;
+      }
+      continue;
+    }
+
+    // Heading — always keep, reset paragraph tracking
+    if (/^#{1,6}\s/.test(line)) {
+      if (omittedLines > 0) {
+        kept.push(`[... ${omittedLines} lines omitted]`);
+        omittedLines = 0;
+      }
+      kept.push(line);
+      currentSectionLines = 0;
+      paragraphKept = false;
+      inParagraph = false;
+      continue;
+    }
+
+    // Empty line — paragraph boundary
+    if (line.trim() === '') {
+      if (inParagraph && !paragraphKept) {
+        // End of first paragraph — mark it kept
+        paragraphKept = true;
+      }
+      if (!paragraphKept || currentSectionLines === 0) {
+        kept.push(line);
+      } else {
+        omittedLines++;
+      }
+      inParagraph = false;
+      continue;
+    }
+
+    // Content line
+    currentSectionLines++;
+    if (!paragraphKept) {
+      // Still in the first paragraph — keep it
+      kept.push(line);
+      inParagraph = true;
+    } else {
+      omittedLines++;
+    }
+  }
+
+  if (omittedLines > 0) {
+    kept.push(`[... ${omittedLines} lines omitted]`);
+  }
+
+  const totalOmitted = lines.length - kept.length;
+  if (totalOmitted > 0) {
+    kept.push('');
+    kept.push(`[Truncated: read .planning/${filename} for full content]`);
+  }
+
+  return kept.join('\n');
+}
+
+// ─── Milestone extraction ───────────────────────────────────────────────────
+
+/**
+ * Extract the current milestone section from a ROADMAP.md.
+ *
+ * Parses STATE.md to find the current milestone name, then extracts only
+ * that milestone's section from the roadmap. Falls back to full content
+ * if the milestone can't be identified or found.
+ */
+export function extractCurrentMilestone(
+  roadmapContent: string,
+  stateContent?: string,
+): string {
+  if (!stateContent) return roadmapContent;
+
+  // Find current milestone from STATE.md
+  // Patterns: "Current Milestone: X", "milestone: X", "## Current Position" block
+  const milestonePatterns = [
+    /current\s*milestone\s*:\s*(.+)/i,
+    /^milestone\s*:\s*(.+)/im,
+    /##\s*current\s*position[\s\S]*?milestone\s*:\s*(.+)/i,
+  ];
+
+  let milestoneName: string | undefined;
+  for (const pattern of milestonePatterns) {
+    const match = stateContent.match(pattern);
+    if (match) {
+      milestoneName = match[1].trim();
+      break;
+    }
+  }
+
+  if (!milestoneName) return roadmapContent;
+
+  // Find the milestone section in roadmap
+  // Look for heading containing the milestone name
+  const lines = roadmapContent.split('\n');
+  let sectionStart = -1;
+  let sectionEnd = lines.length;
+  let sectionHeadingLevel = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const headingMatch = lines[i].match(/^(#{1,6})\s+(.+)/);
+    if (!headingMatch) continue;
+
+    const level = headingMatch[1].length;
+    const title = headingMatch[2];
+
+    if (sectionStart === -1) {
+      // Looking for the milestone heading
+      if (title.toLowerCase().includes(milestoneName.toLowerCase())) {
+        sectionStart = i;
+        sectionHeadingLevel = level;
+      }
+    } else {
+      // Found start — look for next heading at same or higher level
+      if (level <= sectionHeadingLevel) {
+        sectionEnd = i;
+        break;
+      }
+    }
+  }
+
+  if (sectionStart === -1) return roadmapContent;
+
+  // Extract preamble (everything before first milestone heading at the same level)
+  const preamble: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const headingMatch = lines[i].match(/^(#{1,6})\s/);
+    if (headingMatch && headingMatch[1].length === sectionHeadingLevel && i !== sectionStart) {
+      // Hit another milestone-level heading before our section
+      if (i < sectionStart) {
+        break; // preamble ends at first milestone heading
+      }
+    }
+    if (i < sectionStart) {
+      // Keep top-level title and intro
+      if (i === 0 || lines[i].match(/^#\s/) || !lines[i].match(/^#{1,6}\s/)) {
+        preamble.push(lines[i]);
+      }
+    }
+  }
+
+  const milestoneSection = lines.slice(sectionStart, sectionEnd).join('\n');
+  const otherMilestones = countOtherMilestones(lines, sectionHeadingLevel, sectionStart);
+
+  const result = [
+    ...preamble,
+    '',
+    milestoneSection,
+  ];
+
+  if (otherMilestones > 0) {
+    result.push('');
+    result.push(`[${otherMilestones} other milestone(s) omitted — read .planning/ROADMAP.md for full roadmap]`);
+  }
+
+  return result.join('\n').trim();
+}
+
+function countOtherMilestones(
+  lines: string[],
+  headingLevel: number,
+  excludeIndex: number,
+): number {
+  let count = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (i === excludeIndex) continue;
+    const match = lines[i].match(/^(#{1,6})\s/);
+    if (match && match[1].length === headingLevel) {
+      count++;
+    }
+  }
+  return count;
+}