@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/phase-prompt.ts

@@ -0,0 +1,259 @@
+/**
+ * Phase-aware prompt factory — assembles complete prompts for each phase type.
+ *
+ * Reads workflow .md + agent .md files from disk (D006), extracts structured
+ * blocks (<role>, <purpose>, <process>), and composes system prompts with
+ * injected context files per phase type.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { ContextFiles, ParsedPlan } from './types.js';
+import { PhaseType } from './types.js';
+import { buildExecutorPrompt } from './prompt-builder.js';
+import { PHASE_AGENT_MAP } from './tool-scoping.js';
+import { sanitizePrompt } from './prompt-sanitizer.js';
+import { resolveLegacyInstallDir } from './sdk-package-compatibility.js';
+
+// ─── Workflow file mapping ───────────────────────────────────────────────────
+
+/**
+ * Maps phase types to their workflow file names.
+ */
+const PHASE_WORKFLOW_MAP: Record<PhaseType, string> = {
+  [PhaseType.Execute]: 'execute-plan.md',
+  [PhaseType.Research]: 'research-phase.md',
+  [PhaseType.Plan]: 'plan-phase.md',
+  [PhaseType.Verify]: 'verify-phase.md',
+  [PhaseType.Discuss]: 'discuss-phase.md',
+  [PhaseType.Repair]: 'execute-plan.md',
+};
+
+// ─── XML block extraction ────────────────────────────────────────────────────
+
+/**
+ * Extract content from an XML-style block (e.g., <purpose>...</purpose>).
+ * Returns the trimmed inner content, or empty string if not found.
+ */
+export function extractBlock(content: string, tagName: string): string {
+  const regex = new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)<\\/${tagName}>`, 'i');
+  const match = content.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Extract all <step> blocks from a workflow's <process> section.
+ * Returns an array of step contents with their name attributes.
+ */
+export function extractSteps(processContent: string): Array<{ name: string; content: string }> {
+  const steps: Array<{ name: string; content: string }> = [];
+  const stepRegex = /<step\s+name="([^"]*)"[^>]*>([\s\S]*?)<\/step>/gi;
+  let match;
+
+  while ((match = stepRegex.exec(processContent)) !== null) {
+    steps.push({
+      name: match[1],
+      content: match[2].trim(),
+    });
+  }
+
+  return steps;
+}
+
+// ─── YAML frontmatter stripping ─────────────────────────────────────────────
+
+/**
+ * Strip YAML frontmatter (---...---) from an agent definition file,
+ * returning only the markdown/XML content body.
+ */
+export function stripYamlFrontmatter(content: string): string {
+  const match = content.match(/^---\s*\n[\s\S]*?\n---\s*\n?([\s\S]*)$/);
+  return match ? match[1].trim() : content.trim();
+}
+
+// ─── PromptFactory class ─────────────────────────────────────────────────────
+
+export class PromptFactory {
+  private readonly workflowsDir: string;
+  private readonly agentsDir: string;
+  private readonly projectAgentsDir?: string;
+  private readonly sdkPromptsDir: string;
+  private readonly projectDir?: string;
+
+  constructor(options?: {
+    gsdInstallDir?: string;
+    agentsDir?: string;
+    projectAgentsDir?: string;
+    sdkPromptsDir?: string;
+    projectDir?: string;
+  }) {
+    const gsdInstallDir = options?.gsdInstallDir ?? resolveLegacyInstallDir();
+    this.workflowsDir = join(gsdInstallDir, 'workflows');
+    this.agentsDir = options?.agentsDir ?? join(gsdInstallDir, '..', 'agents');
+    this.projectAgentsDir = options?.projectAgentsDir;
+    this.projectDir = options?.projectDir;
+    // SDK prompts dir: explicit override → package-relative default via import.meta.url
+    this.sdkPromptsDir =
+      options?.sdkPromptsDir ??
+      join(fileURLToPath(new URL('.', import.meta.url)), '..', 'prompts');
+  }
+
+  /**
+   * Build a complete prompt for the given phase type.
+   *
+   * For execute phase with a plan, delegates to buildExecutorPrompt().
+   * For other phases, assembles: role + purpose + process steps + context.
+   */
+  async buildPrompt(
+    phaseType: PhaseType,
+    plan: ParsedPlan | null,
+    contextFiles: ContextFiles,
+    phaseDir?: string,
+  ): Promise<string> {
+    // Execute phase with a plan: delegate to existing buildExecutorPrompt
+    if (phaseType === PhaseType.Execute && plan) {
+      const agentDef = await this.loadAgentDef(phaseType);
+      return sanitizePrompt(buildExecutorPrompt(plan, { agentDef, phaseDir }), this.projectDir);
+    }
+
+    // Prompt assembly order is cache-optimized (#1614):
+    // Stable prefix (deterministic per phase type) → cached by Anthropic at 0.1x cost
+    // Variable suffix (.planning/ files) → uncached, changes per project/run
+    const sections: string[] = [];
+
+    // ── STABLE PREFIX (cacheable across runs for the same phase type) ──
+
+    // ── Full agent definition ──
+    // Include the complete agent definition (minus YAML frontmatter), not just
+    // the <role> block. The real agents have critical instructions in sections
+    // like <philosophy>, <task_breakdown>, <plan_format>, <execution_flow>,
+    // <scope_estimation>, <context_fidelity>, <checkpoints>, etc.
+    const agentDef = await this.loadAgentDef(phaseType);
+    if (agentDef) {
+      const agentContent = stripYamlFrontmatter(agentDef);
+      if (agentContent) {
+        sections.push(`## Agent Instructions\n\n${agentContent}`);
+      }
+    }
+
+    // ── Workflow purpose + process ──
+    const workflow = await this.loadWorkflowFile(phaseType);
+    if (workflow) {
+      const purpose = extractBlock(workflow, 'purpose');
+      if (purpose) {
+        sections.push(`## Purpose\n\n${purpose}`);
+      }
+
+      const process = extractBlock(workflow, 'process');
+      if (process) {
+        const steps = extractSteps(process);
+        if (steps.length > 0) {
+          const stepBlocks = steps.map((s) => `### ${s.name}\n\n${s.content}`).join('\n\n');
+          sections.push(`## Process\n\n${stepBlocks}`);
+        }
+      }
+    }
+
+    // ── VARIABLE SUFFIX (project-specific, changes per run) ──
+
+    // ── Context files ──
+    const contextSection = this.formatContextFiles(contextFiles);
+    if (contextSection) {
+      sections.push(contextSection);
+    }
+
+    return sanitizePrompt(sections.join('\n\n'), this.projectDir);
+  }
+
+  /**
+   * Load the workflow file for a phase type.
+   * Tries installed GSD workflows first (the complete, up-to-date versions),
+   * then falls back to SDK bundled copies only if installed not found.
+   * Returns the raw content, or undefined if not found.
+   */
+  async loadWorkflowFile(phaseType: PhaseType): Promise<string | undefined> {
+    const filename = PHASE_WORKFLOW_MAP[phaseType];
+
+    // Try installed GSD workflows first (complete versions)
+    const paths = [
+      join(this.workflowsDir, filename),
+      join(this.sdkPromptsDir, 'workflows', filename),
+    ];
+
+    for (const p of paths) {
+      try {
+        return await readFile(p, 'utf-8');
+      } catch {
+        // Not found at this path, try next
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Load the agent definition for a phase type.
+   * Tries installed agents first (the complete, up-to-date versions),
+   * then SDK bundled copies as last resort.
+   * Returns undefined if no agent is mapped or file not found.
+   */
+  async loadAgentDef(phaseType: PhaseType): Promise<string | undefined> {
+    const agentFilename = PHASE_AGENT_MAP[phaseType];
+    if (!agentFilename) return undefined;
+
+    // Priority: installed agents → project-level → SDK bundled (last resort)
+    const paths = [
+      join(this.agentsDir, agentFilename),
+    ];
+
+    if (this.projectAgentsDir) {
+      paths.push(join(this.projectAgentsDir, agentFilename));
+    }
+
+    // SDK bundled copies are last resort only
+    paths.push(join(this.sdkPromptsDir, 'agents', agentFilename));
+
+    for (const p of paths) {
+      try {
+        return await readFile(p, 'utf-8');
+      } catch {
+        // Not found at this path, try next
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Format context files into a prompt section.
+   */
+  private formatContextFiles(contextFiles: ContextFiles): string | null {
+    const entries: string[] = [];
+
+    const fileLabels: Record<keyof ContextFiles, string> = {
+      state: 'Project State (STATE.md)',
+      roadmap: 'Roadmap (ROADMAP.md)',
+      context: 'Context (CONTEXT.md)',
+      research: 'Research (RESEARCH.md)',
+      requirements: 'Requirements (REQUIREMENTS.md)',
+      config: 'Config (config.json)',
+      plan: 'Plan (PLAN.md)',
+      summary: 'Summary (SUMMARY.md)',
+    };
+
+    for (const [key, label] of Object.entries(fileLabels)) {
+      const content = contextFiles[key as keyof ContextFiles];
+      if (content) {
+        entries.push(`### ${label}\n\n${content}`);
+      }
+    }
+
+    if (entries.length === 0) return null;
+    return `## Context\n\n${entries.join('\n\n')}`;
+  }
+
+}
+
+export { PHASE_WORKFLOW_MAP };

package/sdk/src/phase-runner.integration.test.ts

@@ -0,0 +1,377 @@
+/**
+ * Integration test — proves PhaseRunner state machine works against real gsd-tools.cjs.
+ *
+ * Creates a temp `.planning/` directory structure, instantiates real GSDTools,
+ * and exercises the state machine. Sessions will fail (no Claude CLI in CI) but
+ * the state machine's control flow, event emission, and error capture are proven.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { GSDTools, resolveGsdToolsPath } from './gsd-tools.js';
+import { PhaseRunner } from './phase-runner.js';
+import type { PhaseRunnerDeps } from './phase-runner.js';
+import { ContextEngine } from './context-engine.js';
+import { PromptFactory } from './phase-prompt.js';
+import { GSDEventStream } from './event-stream.js';
+import { loadConfig } from './config.js';
+import type { GSDEvent } from './types.js';
+import { GSDEventType, PhaseStepType } from './types.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const GSD_TOOLS_PATH = resolveGsdToolsPath(process.cwd());
+const gsdToolsAvailable = existsSync(GSD_TOOLS_PATH);
+
+async function createTempPlanningDir(): Promise<string> {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'gsd-sdk-phase-int-'));
+
+  // Create .planning structure
+  const planningDir = join(tmpDir, '.planning');
+  const phasesDir = join(planningDir, 'phases');
+  const phaseDir = join(phasesDir, '01-integration-test');
+
+  await mkdir(phaseDir, { recursive: true });
+
+  // config.json
+  await writeFile(
+    join(planningDir, 'config.json'),
+    JSON.stringify({
+      model_profile: 'balanced',
+      commit_docs: false,
+      workflow: {
+        research: true,
+        verifier: true,
+        auto_advance: true,
+        skip_discuss: false,
+      },
+    }),
+  );
+
+  // ROADMAP.md — required for roadmap_exists
+  await writeFile(join(planningDir, 'ROADMAP.md'), '# Roadmap\n\n## Phase 01: Integration Test\n');
+
+  // CONTEXT.md in phase dir — triggers has_context=true → discuss is skipped
+  await writeFile(
+    join(phaseDir, 'CONTEXT.md'),
+    '# Context\n\nThis is an integration test phase with pre-existing context.\n',
+  );
+
+  return tmpDir;
+}
+
+// ─── Test suite ──────────────────────────────────────────────────────────────
+
+describe.skipIf(!gsdToolsAvailable)('Integration: PhaseRunner against real gsd-tools.cjs', () => {
+  let tmpDir: string;
+  let tools: GSDTools;
+
+  beforeAll(async () => {
+    tmpDir = await createTempPlanningDir();
+    tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: GSD_TOOLS_PATH,
+      timeoutMs: 10_000,
+    });
+  });
+
+  afterAll(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  // ── Test 1: initPhaseOp returns valid PhaseOpInfo ──
+
+  it('initPhaseOp returns valid PhaseOpInfo for temp phase', async () => {
+    const info = await tools.initPhaseOp('01');
+
+    expect(info.phase_found).toBe(true);
+    expect(info.phase_number).toBe('01');
+    expect(info.phase_name).toBe('integration-test');
+    expect(info.phase_dir).toBe('.planning/phases/01-integration-test');
+    expect(info.has_context).toBe(true);
+    expect(info.has_plans).toBe(false);
+    expect(info.plan_count).toBe(0);
+    expect(info.roadmap_exists).toBe(true);
+    expect(info.planning_exists).toBe(true);
+  });
+
+  it('initPhaseOp returns phase_found=false for nonexistent phase', async () => {
+    const info = await tools.initPhaseOp('99');
+
+    expect(info.phase_found).toBe(false);
+    expect(info.has_context).toBe(false);
+    expect(info.plan_count).toBe(0);
+  });
+
+  // ── Test 2: PhaseRunner state machine control flow ──
+
+  it('PhaseRunner emits lifecycle events and captures session errors gracefully', { timeout: 300_000 }, async () => {
+    const eventStream = new GSDEventStream();
+    const config = await loadConfig(tmpDir);
+    const contextEngine = new ContextEngine(tmpDir);
+    const promptFactory = new PromptFactory();
+
+    const events: GSDEvent[] = [];
+    eventStream.on('event', (e: GSDEvent) => events.push(e));
+
+    const deps: PhaseRunnerDeps = {
+      projectDir: tmpDir,
+      tools,
+      promptFactory,
+      contextEngine,
+      eventStream,
+      config,
+    };
+
+    const runner = new PhaseRunner(deps);
+    // Tight budget/turns so each session finishes fast
+    const result = await runner.run('01', {
+      maxTurnsPerStep: 2,
+      maxBudgetPerStep: 0.10,
+    });
+
+    // ── (a) Phase start event emitted ──
+    const phaseStartEvents = events.filter(e => e.type === GSDEventType.PhaseStart);
+    expect(phaseStartEvents).toHaveLength(1);
+    const phaseStart = phaseStartEvents[0]!;
+    if (phaseStart.type === GSDEventType.PhaseStart) {
+      expect(phaseStart.phaseNumber).toBe('01');
+      expect(phaseStart.phaseName).toBe('integration-test');
+    }
+
+    // ── (b) Discuss should be skipped (has_context=true) ──
+    // No discuss step in results since it was skipped
+    const discussSteps = result.steps.filter(s => s.step === PhaseStepType.Discuss);
+    expect(discussSteps).toHaveLength(0);
+
+    // ── (c) Step start events emitted for attempted steps ──
+    const stepStartEvents = events.filter(e => e.type === GSDEventType.PhaseStepStart);
+    expect(stepStartEvents.length).toBeGreaterThanOrEqual(1);
+
+    // ── (d) Step results are properly structured ──
+    // With CLI available, sessions may succeed or fail depending on budget/turns.
+    // Either way, each step result must have correct structure.
+    expect(result.steps.length).toBeGreaterThanOrEqual(1);
+    for (const step of result.steps) {
+      expect(Object.values(PhaseStepType)).toContain(step.step);
+      expect(typeof step.success).toBe('boolean');
+      expect(typeof step.durationMs).toBe('number');
+      // Failed steps may or may not have an error message
+      // (e.g. advance step can fail without explicit error string)
+    }
+
+    // ── (e) Phase complete event emitted ──
+    const phaseCompleteEvents = events.filter(e => e.type === GSDEventType.PhaseComplete);
+    expect(phaseCompleteEvents).toHaveLength(1);
+
+    // ── (f) Result structure is valid ──
+    expect(result.phaseNumber).toBe('01');
+    expect(result.phaseName).toBe('integration-test');
+    expect(typeof result.totalCostUsd).toBe('number');
+    expect(typeof result.totalDurationMs).toBe('number');
+    expect(result.totalDurationMs).toBeGreaterThan(0);
+  });
+
+  // ── Test 3: PhaseRunner with nonexistent phase throws ──
+
+  it('PhaseRunner throws PhaseRunnerError for nonexistent phase', async () => {
+    const eventStream = new GSDEventStream();
+    const config = await loadConfig(tmpDir);
+    const contextEngine = new ContextEngine(tmpDir);
+    const promptFactory = new PromptFactory();
+
+    const deps: PhaseRunnerDeps = {
+      projectDir: tmpDir,
+      tools,
+      promptFactory,
+      contextEngine,
+      eventStream,
+      config,
+    };
+
+    const runner = new PhaseRunner(deps);
+    await expect(runner.run('99')).rejects.toThrow('Phase 99 not found on disk');
+  });
+
+  // ── Test 4: GSD.runPhase() public API delegates correctly ──
+
+  it('GSD.runPhase() creates collaborators and delegates to PhaseRunner', { timeout: 300_000 }, async () => {
+    // Import GSD here to test the public API wiring
+    const { GSD } = await import('./index.js');
+
+    const gsd = new GSD({ projectDir: tmpDir });
+    const events: GSDEvent[] = [];
+    gsd.onEvent((e) => events.push(e));
+
+    const result = await gsd.runPhase('01', {
+      maxTurnsPerStep: 2,
+      maxBudgetPerStep: 0.10,
+    });
+
+    // Proves the full wiring works: GSD → PhaseRunner → GSDTools → gsd-tools.cjs
+    expect(result.phaseNumber).toBe('01');
+    expect(result.phaseName).toBe('integration-test');
+    expect(result.steps.length).toBeGreaterThanOrEqual(1);
+    expect(events.some(e => e.type === GSDEventType.PhaseStart)).toBe(true);
+    expect(events.some(e => e.type === GSDEventType.PhaseComplete)).toBe(true);
+  });
+});
+
+// ─── Wave / phasePlanIndex Integration Tests ─────────────────────────────────
+
+/**
+ * Creates a temp `.planning/` directory with multi-wave plan files.
+ * - Plans 01 and 02 are wave 1 (parallel)
+ * - Plan 03 is wave 2 (depends on wave 1)
+ * - Plan 01 has a SUMMARY.md (marks it as completed)
+ */
+async function createMultiWavePlanningDir(): Promise<string> {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'gsd-sdk-wave-int-'));
+
+  const planningDir = join(tmpDir, '.planning');
+  const phaseDir = join(planningDir, 'phases', '01-wave-test');
+  await mkdir(phaseDir, { recursive: true });
+
+  // config.json — with parallelization enabled
+  await writeFile(
+    join(planningDir, 'config.json'),
+    JSON.stringify({
+      model_profile: 'balanced',
+      commit_docs: false,
+      parallelization: true,
+      workflow: {
+        research: true,
+        verifier: true,
+        auto_advance: true,
+        skip_discuss: false,
+      },
+    }),
+  );
+
+  // ROADMAP.md
+  await writeFile(join(planningDir, 'ROADMAP.md'), '# Roadmap\n\n## Phase 01: Wave Test\n');
+
+  const planTemplate = (id: string, wave: number, dependsOn: string[] = []) => `---
+phase: "01"
+plan: "${id}"
+type: "feature"
+wave: ${wave}
+depends_on: [${dependsOn.map(d => `"${d}"`).join(', ')}]
+files_modified: ["src/${id}.ts"]
+autonomous: true
+requirements: []
+must_haves:
+  truths: ["${id} exists"]
+  artifacts: []
+  key_links: []
+---
+
+# Plan: ${id}
+
+<task type="code" name="Create ${id}" files="src/${id}.ts">
+  <read_first>none</read_first>
+  <action>Create ${id}</action>
+  <verify>File exists</verify>
+  <acceptance_criteria>
+    - File exists
+  </acceptance_criteria>
+  <done>Done</done>
+</task>
+`;
+
+  // Wave 1 plans (parallel)
+  await writeFile(join(phaseDir, '01-wave-test-01-PLAN.md'), planTemplate('01-wave-test-01', 1));
+  await writeFile(join(phaseDir, '01-wave-test-02-PLAN.md'), planTemplate('01-wave-test-02', 1));
+
+  // Wave 2 plan (depends on wave 1)
+  await writeFile(
+    join(phaseDir, '01-wave-test-03-PLAN.md'),
+    planTemplate('01-wave-test-03', 2, ['01-wave-test-01']),
+  );
+
+  // Summary for plan 01 — marks it as completed
+  await writeFile(
+    join(phaseDir, '01-wave-test-01-SUMMARY.md'),
+    `---\nresult: pass\nplan: "01-wave-test-01"\ncost_usd: 0.01\nduration_ms: 1000\n---\n\n# Summary\n\nAll tasks completed.\n`,
+  );
+
+  return tmpDir;
+}
+
+describe.skipIf(!gsdToolsAvailable)('Integration: phasePlanIndex and wave execution', () => {
+  let tmpDir: string;
+  let tools: GSDTools;
+
+  beforeAll(async () => {
+    tmpDir = await createMultiWavePlanningDir();
+    tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: GSD_TOOLS_PATH,
+      timeoutMs: 10_000,
+    });
+  });
+
+  afterAll(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('phasePlanIndex returns typed PhasePlanIndex with correct wave grouping', async () => {
+    const index = await tools.phasePlanIndex('01');
+
+    // 3 plans total
+    expect(index.plans).toHaveLength(3);
+
+    // Wave grouping: wave 1 has 2 plans, wave 2 has 1
+    expect(index.waves['1']).toHaveLength(2);
+    expect(index.waves['1']).toContain('01-wave-test-01');
+    expect(index.waves['1']).toContain('01-wave-test-02');
+    expect(index.waves['2']).toHaveLength(1);
+    expect(index.waves['2']).toContain('01-wave-test-03');
+
+    // Incomplete: plan 01 has summary so only 02 and 03 are incomplete
+    expect(index.incomplete).toHaveLength(2);
+    expect(index.incomplete).toContain('01-wave-test-02');
+    expect(index.incomplete).toContain('01-wave-test-03');
+
+    // All autonomous → no checkpoints
+    expect(index.has_checkpoints).toBe(false);
+
+    // Phase ID correct
+    expect(index.phase).toBe('01');
+  });
+
+  it('phasePlanIndex marks has_summary correctly per plan', async () => {
+    const index = await tools.phasePlanIndex('01');
+
+    // Plan 01 has a SUMMARY.md on disk
+    const plan01 = index.plans.find(p => p.id === '01-wave-test-01');
+    expect(plan01).toBeDefined();
+    expect(plan01!.has_summary).toBe(true);
+
+    // Plans 02 and 03 have no summary
+    const plan02 = index.plans.find(p => p.id === '01-wave-test-02');
+    expect(plan02).toBeDefined();
+    expect(plan02!.has_summary).toBe(false);
+
+    const plan03 = index.plans.find(p => p.id === '01-wave-test-03');
+    expect(plan03).toBeDefined();
+    expect(plan03!.has_summary).toBe(false);
+  });
+
+  it('phasePlanIndex for nonexistent phase returns empty plans', async () => {
+    const index = await tools.phasePlanIndex('99');
+
+    expect(index.plans).toHaveLength(0);
+    expect(Object.keys(index.waves)).toHaveLength(0);
+    expect(index.incomplete).toHaveLength(0);
+    expect(index.has_checkpoints).toBe(false);
+  });
+});