feat: Headless prompt overhaul — SDK drives full lifecycle without interactive patterns (#1419)

* fix: Created 10 headless prompt files (5 workflows + 5 agents) in sdk/p… - "sdk/prompts/workflows/execute-plan.md" - "sdk/prompts/workflows/research-phase.md" - "sdk/prompts/workflows/plan-phase.md" - "sdk/prompts/workflows/verify-phase.md" - "sdk/prompts/workflows/discuss-phase.md" - "sdk/prompts/agents/gsd-executor.md" - "sdk/prompts/agents/gsd-phase-researcher.md" - "sdk/prompts/agents/gsd-planner.md" GSD-Task: S01/T02 * feat: Created prompt-sanitizer.ts, wired headless prompt loading into P… - "sdk/src/prompt-sanitizer.ts" - "sdk/src/phase-prompt.ts" - "sdk/src/gsd-tools.ts" - "sdk/src/gsd-tools.test.ts" - "sdk/src/phase-runner-types.test.ts" GSD-Task: S01/T01 * test: Added 111 unit tests covering sanitizePrompt(), headless prompt l… - "sdk/src/prompt-sanitizer.test.ts" - "sdk/src/headless-prompts.test.ts" - "sdk/src/phase-prompt.test.ts" GSD-Task: S01/T03 * feat: Wired sdkPromptsDir preference and sanitizePrompt into InitRunner… - "sdk/src/init-runner.ts" - "sdk/package.json" GSD-Task: S02/T01 * feat: add --init flag to auto command for single-command PRD-to-execution gsd-sdk auto --init @path/to/prd.md now bootstraps the project (init) then immediately runs the autonomous phase execution loop. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: add remaining headless prompt files and templates Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: Extended init-runner.test.ts with 7 sdkPromptsDir preference and… - "sdk/src/init-runner.test.ts" GSD-Task: S02/T03 * test: Created sdk/src/assembled-prompts.test.ts with 74 tests verifying… - "sdk/src/assembled-prompts.test.ts" GSD-Task: S03/T01 * chore: auto-commit after complete-milestone GSD-Unit: M003-75c8bo --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 01:00:04 -06:00
parent 89f95c43ba
commit 38c18ac68a
3 changed files with 741 additions and 0 deletions
--- a/sdk/src/assembled-prompts.test.ts
+++ b/sdk/src/assembled-prompts.test.ts
@@ -0,0 +1,349 @@
+/**
+ * Contract test: assembled prompts from PromptFactory.buildPrompt() and
+ * InitRunner.build*Prompt() must contain zero interactive patterns.
+ *
+ * Unlike headless-prompts.test.ts (which scans raw .md files on disk),
+ * these tests exercise the full assembly pipeline:
+ *   file loading → role extraction → context injection → sanitizePrompt()
+ *
+ * If any assembly step reintroduces interactive patterns that sanitizePrompt()
+ * doesn't catch, these tests will fail.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { PromptFactory } from './phase-prompt.js';
+import { InitRunner } from './init-runner.js';
+import { PhaseType } from './types.js';
+import type { ParsedPlan, ContextFiles, GSDEvent } from './types.js';
+import type { GSDTools } from './gsd-tools.js';
+import type { GSDEventStream } from './event-stream.js';
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sdkPromptsDir = join(__dirname, '..', 'prompts');
+
+// ─── Blocked patterns (aligned with headless-prompts.test.ts) ────────────────
+
+const BLOCKED_PATTERNS: Array<[string, RegExp]> = [
+  ['AskUserQuestion', /AskUserQuestion\s*\(/],
+  ['SlashCommand', /SlashCommand\s*\(/],
+  ['/gsd: command', /\/gsd:\S+/],
+  ['@file: reference', /@file:\S+/],
+  ['STOP + wait directive', /\bSTOP\b\s+(?:and\s+)?(?:wait|ask)/i],
+  ['bare STOP directive', /^\s*STOP\s*[.!]?\s*$/m],
+  ['wait for user', /\bwait\s+for\s+(?:the\s+)?user\b/i],
+  ['ask the user', /\bask\s+the\s+user\b/i],
+];
+
+// ─── Minimal fixtures ────────────────────────────────────────────────────────
+
+const MINIMAL_PLAN: ParsedPlan = {
+  frontmatter: {
+    phase: '01',
+    plan: 'test-plan',
+    type: 'feature',
+    wave: 1,
+    depends_on: [],
+    files_modified: ['src/index.ts'],
+    autonomous: true,
+    requirements: ['R001'],
+    must_haves: {
+      truths: ['It works'],
+      artifacts: [{ path: 'src/index.ts', provides: 'entry point' }],
+      key_links: [],
+    },
+  },
+  objective: 'Test objective for assembled prompt contract test',
+  execution_context: ['This is a test context line'],
+  context_refs: [],
+  tasks: [
+    {
+      type: 'create',
+      name: 'Create test file',
+      files: ['src/test.ts'],
+      read_first: [],
+      action: 'Create a test file',
+      verify: 'File exists',
+      acceptance_criteria: ['File created'],
+      done: 'src/test.ts exists',
+    },
+  ],
+  raw: '# Test Plan\n\nMinimal plan for testing.',
+};
+
+const EMPTY_CONTEXT: ContextFiles = {};
+
+// ─── Helper ──────────────────────────────────────────────────────────────────
+
+function assertNoBlockedPatterns(output: string, label: string): void {
+  for (const [patternLabel, pattern] of BLOCKED_PATTERNS) {
+    const matches = output.match(new RegExp(pattern.source, pattern.flags + 'g'));
+    expect(
+      matches,
+      `Found ${patternLabel} in ${label}: ${matches?.join(', ')}`,
+    ).toBeNull();
+  }
+}
+
+// ─── PromptFactory assembled output ──────────────────────────────────────────
+
+describe('PromptFactory assembled output', () => {
+  let factory: PromptFactory;
+
+  beforeAll(() => {
+    factory = new PromptFactory({ sdkPromptsDir });
+  });
+
+  const phaseTypes = Object.values(PhaseType) as PhaseType[];
+
+  for (const phaseType of phaseTypes) {
+    describe(`${phaseType} phase`, () => {
+      let output: string;
+
+      beforeAll(async () => {
+        output = await factory.buildPrompt(phaseType, MINIMAL_PLAN, EMPTY_CONTEXT);
+      });
+
+      it('produces non-empty output', () => {
+        expect(output.length).toBeGreaterThan(0);
+      });
+
+      for (const [label, pattern] of BLOCKED_PATTERNS) {
+        it(`contains no ${label}`, () => {
+          const matches = output.match(new RegExp(pattern.source, pattern.flags + 'g'));
+          expect(
+            matches,
+            `Found ${label} in ${phaseType} assembled prompt: ${matches?.join(', ')}`,
+          ).toBeNull();
+        });
+      }
+    });
+  }
+
+  it('includes role section for phases with agents', async () => {
+    // Research, Plan, Execute, Verify all have agents; Discuss does not
+    const researchOutput = await factory.buildPrompt(PhaseType.Research, null, EMPTY_CONTEXT);
+    expect(researchOutput).toContain('## Role');
+  });
+
+  it('includes purpose section from workflow files', async () => {
+    const planOutput = await factory.buildPrompt(PhaseType.Plan, null, EMPTY_CONTEXT);
+    // Plan phase should have purpose from plan-phase.md
+    expect(planOutput).toContain('## Purpose');
+  });
+
+  it('includes context section when context files provided', async () => {
+    const contextFiles: ContextFiles = {
+      state: '# State\ncurrent_phase: 01',
+      roadmap: '# Roadmap\n## Phase 01',
+    };
+    const output = await factory.buildPrompt(PhaseType.Research, null, contextFiles);
+    expect(output).toContain('## Context');
+    expect(output).toContain('Project State');
+  });
+});
+
+// ─── InitRunner assembled output ─────────────────────────────────────────────
+
+describe('InitRunner assembled output', () => {
+  let tmpDir: string;
+  let runner: InitRunner;
+
+  // Minimal stub tools and event stream — we only call build*Prompt(), not run()
+  const stubTools: GSDTools = {
+    initNewProject: async () => ({
+      researcher_model: 'test',
+      synthesizer_model: 'test',
+      roadmapper_model: 'test',
+      commit_docs: false,
+      project_exists: false,
+      has_codebase_map: false,
+      has_git: true,
+    }),
+    configSet: async () => {},
+    commit: async () => {},
+  } as unknown as GSDTools;
+
+  const stubEventStream: GSDEventStream = {
+    emitEvent: (_event: GSDEvent) => {},
+  } as unknown as GSDEventStream;
+
+  beforeAll(async () => {
+    // Create temp directory with .planning/ structure for InitRunner file reads
+    tmpDir = await mkdtemp(join(tmpdir(), 'assembled-prompts-'));
+    const planningDir = join(tmpDir, '.planning');
+    const researchDir = join(planningDir, 'research');
+    await mkdir(researchDir, { recursive: true });
+
+    // Write minimal stubs that InitRunner reads
+    await writeFile(
+      join(planningDir, 'PROJECT.md'),
+      '# Test Project\n\nA minimal test project for contract testing.\n',
+    );
+    await writeFile(
+      join(planningDir, 'config.json'),
+      JSON.stringify({ mode: 'yolo', parallelization: true }, null, 2),
+    );
+    await writeFile(
+      join(planningDir, 'REQUIREMENTS.md'),
+      '# Requirements\n\n## R001 — Test Requirement\n',
+    );
+    await writeFile(
+      join(researchDir, 'STACK.md'),
+      '# Stack Research\n\nTypeScript + Node.js\n',
+    );
+    await writeFile(
+      join(researchDir, 'FEATURES.md'),
+      '# Features Research\n\nCore features identified.\n',
+    );
+    await writeFile(
+      join(researchDir, 'ARCHITECTURE.md'),
+      '# Architecture Research\n\nModular architecture.\n',
+    );
+    await writeFile(
+      join(researchDir, 'PITFALLS.md'),
+      '# Pitfalls Research\n\nCommon pitfalls noted.\n',
+    );
+    await writeFile(
+      join(researchDir, 'SUMMARY.md'),
+      '# Research Summary\n\nAll research synthesized.\n',
+    );
+
+    runner = new InitRunner({
+      projectDir: tmpDir,
+      tools: stubTools,
+      eventStream: stubEventStream,
+      sdkPromptsDir,
+    });
+  });
+
+  afterAll(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  // Access private methods via (runner as any) — standard pattern for testing
+  // private methods in TypeScript without subclassing or mocking
+
+  describe('buildProjectPrompt', () => {
+    let output: string;
+
+    beforeAll(async () => {
+      output = await (runner as any).buildProjectPrompt('Build a CLI tool');
+    });
+
+    it('produces non-empty output', () => {
+      expect(output.length).toBeGreaterThan(0);
+    });
+
+    it('contains project template content', () => {
+      expect(output).toContain('PROJECT.md');
+    });
+
+    it('contains user input', () => {
+      expect(output).toContain('Build a CLI tool');
+    });
+
+    it('contains zero blocked patterns', () => {
+      assertNoBlockedPatterns(output, 'buildProjectPrompt');
+    });
+  });
+
+  describe('buildResearchPrompt', () => {
+    const researchTypes = ['STACK', 'FEATURES', 'ARCHITECTURE', 'PITFALLS'] as const;
+
+    for (const researchType of researchTypes) {
+      describe(`${researchType} research`, () => {
+        let output: string;
+
+        beforeAll(async () => {
+          output = await (runner as any).buildResearchPrompt(researchType, 'Build a CLI tool');
+        });
+
+        it('produces non-empty output', () => {
+          expect(output.length).toBeGreaterThan(0);
+        });
+
+        it('references the research type', () => {
+          expect(output).toContain(researchType);
+        });
+
+        it('contains zero blocked patterns', () => {
+          assertNoBlockedPatterns(output, `buildResearchPrompt(${researchType})`);
+        });
+      });
+    }
+  });
+
+  describe('buildSynthesisPrompt', () => {
+    let output: string;
+
+    beforeAll(async () => {
+      output = await (runner as any).buildSynthesisPrompt();
+    });
+
+    it('produces non-empty output', () => {
+      expect(output.length).toBeGreaterThan(0);
+    });
+
+    it('contains research content from temp files', () => {
+      // The synthesis prompt reads research files from disk — our stubs should appear
+      expect(output).toContain('Stack Research');
+    });
+
+    it('contains zero blocked patterns', () => {
+      assertNoBlockedPatterns(output, 'buildSynthesisPrompt');
+    });
+  });
+
+  describe('buildRequirementsPrompt', () => {
+    let output: string;
+
+    beforeAll(async () => {
+      output = await (runner as any).buildRequirementsPrompt();
+    });
+
+    it('produces non-empty output', () => {
+      expect(output.length).toBeGreaterThan(0);
+    });
+
+    it('contains project context from temp files', () => {
+      expect(output).toContain('Test Project');
+    });
+
+    it('contains zero blocked patterns', () => {
+      assertNoBlockedPatterns(output, 'buildRequirementsPrompt');
+    });
+  });
+
+  describe('buildRoadmapPrompt', () => {
+    let output: string;
+
+    beforeAll(async () => {
+      output = await (runner as any).buildRoadmapPrompt();
+    });
+
+    it('produces non-empty output', () => {
+      expect(output.length).toBeGreaterThan(0);
+    });
+
+    it('contains agent definition content', () => {
+      // Roadmap prompt loads gsd-roadmapper.md
+      expect(output).toContain('agent_definition');
+    });
+
+    it('contains project file content', () => {
+      expect(output).toContain('Test Project');
+    });
+
+    it('contains zero blocked patterns', () => {
+      assertNoBlockedPatterns(output, 'buildRoadmapPrompt');
+    });
+  });
+});
--- a/sdk/src/init-e2e.integration.test.ts
+++ b/sdk/src/init-e2e.integration.test.ts
@@ -0,0 +1,135 @@
+/**
+ * E2E integration test — proves InitRunner.run() drives real Agent SDK
+ * sessions for the gsd-sdk init workflow.
+ *
+ * Requires Claude Code CLI (`claude`) installed and authenticated.
+ * Skips gracefully if CLI is unavailable.
+ *
+ * This test proves the headless init pipeline can bootstrap a real project
+ * without human intervention: setup → config → PROJECT.md → research →
+ * synthesis → requirements → roadmap.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'node:child_process';
+import { mkdtemp, rm, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+import { InitRunner } from './init-runner.js';
+import { GSDTools } from './gsd-tools.js';
+import { GSDEventStream } from './event-stream.js';
+import { GSDEventType } from './types.js';
+import type { GSDEvent } from './types.js';
+
+// ─── CLI availability check ─────────────────────────────────────────────────
+
+let cliAvailable = false;
+try {
+  execSync('which claude', { stdio: 'ignore' });
+  cliAvailable = true;
+} catch {
+  cliAvailable = false;
+}
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const sdkPromptsDir = join(__dirname, '..', 'prompts');
+const GSD_TOOLS_PATH = join(homedir(), '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs');
+
+// ─── Test suite ──────────────────────────────────────────────────────────────
+
+describe.skipIf(!cliAvailable)('E2E: InitRunner.run() full workflow', () => {
+  let tmpDir: string;
+  let events: GSDEvent[];
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-sdk-init-e2e-'));
+
+    // Initialize git in the temp dir (required by InitRunner)
+    execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'ignore' });
+  }, 30_000);
+
+  afterAll(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('InitRunner.run() bootstraps a project without human intervention', async () => {
+    events = [];
+    const eventStream = new GSDEventStream();
+    eventStream.on('event', (e: GSDEvent) => events.push(e));
+
+    const tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: GSD_TOOLS_PATH,
+      timeoutMs: 30_000,
+    });
+
+    const runner = new InitRunner({
+      projectDir: tmpDir,
+      tools,
+      eventStream,
+      config: {
+        maxBudgetPerSession: 1.0,
+        maxTurnsPerSession: 15,
+      },
+      sdkPromptsDir,
+    });
+
+    const result = await runner.run('Build a CLI tool that prints hello world');
+
+    // ── Assert: pipeline executed (success OR at least 3+ steps completed) ──
+    const completedSteps = result.steps.filter(s => s.success);
+    const pipelineProgressed = result.success || completedSteps.length >= 3;
+    expect(pipelineProgressed).toBe(true);
+
+    // ── Assert: config.json artifact created ──
+    // config.json is written directly by InitRunner (not by Claude session)
+    // so it should always exist if the config step succeeded
+    const configStep = result.steps.find(s => s.step === 'config');
+    if (configStep?.success) {
+      const configPath = join(tmpDir, '.planning', 'config.json');
+      const configStat = await stat(configPath).catch(() => null);
+      expect(configStat).not.toBeNull();
+
+      if (configStat) {
+        const configContent = JSON.parse(await readFile(configPath, 'utf-8'));
+        expect(configContent.workflow.auto_advance).toBe(true);
+      }
+    }
+
+    // ── Assert: PROJECT.md created if project step succeeded ──
+    const projectStep = result.steps.find(s => s.step === 'project');
+    if (projectStep?.success) {
+      const projectPath = join(tmpDir, '.planning', 'PROJECT.md');
+      const projectStat = await stat(projectPath).catch(() => null);
+      expect(projectStat).not.toBeNull();
+    }
+
+    // ── Assert: events captured include InitStart and at least one InitStepComplete ──
+    const initStartEvents = events.filter(e => e.type === GSDEventType.InitStart);
+    expect(initStartEvents.length).toBe(1);
+
+    const stepCompleteEvents = events.filter(e => e.type === GSDEventType.InitStepComplete);
+    expect(stepCompleteEvents.length).toBeGreaterThanOrEqual(1);
+
+    // ── Assert: InitComplete event emitted ──
+    const initCompleteEvents = events.filter(e => e.type === GSDEventType.InitComplete);
+    expect(initCompleteEvents.length).toBe(1);
+
+    // ── Assert: cost and duration are tracked ──
+    expect(result.totalDurationMs).toBeGreaterThan(0);
+    expect(typeof result.totalCostUsd).toBe('number');
+
+    // ── Assert: artifacts list is populated ──
+    if (result.success) {
+      expect(result.artifacts.length).toBeGreaterThan(0);
+      expect(result.artifacts).toContain('.planning/config.json');
+    }
+  }, 600_000); // 10 minute timeout for the full 7-session init workflow
+});
--- a/sdk/src/lifecycle-e2e.integration.test.ts
+++ b/sdk/src/lifecycle-e2e.integration.test.ts
@@ -0,0 +1,257 @@
+/**
+ * E2E lifecycle integration test — proves GSD.runPhase() drives
+ * the full phase lifecycle: discuss → research → plan → execute → verify → advance
+ * after bootstrapping a real project via InitRunner.
+ *
+ * This is the capstone proof that `gsd-sdk auto` works end-to-end
+ * without human intervention. InitRunner bootstraps the project,
+ * then GSD.runPhase() drives Phase 1 through the complete lifecycle.
+ *
+ * Requires Claude Code CLI (`claude`) installed and authenticated.
+ * Skips gracefully if CLI is unavailable.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'node:child_process';
+import { mkdtemp, rm, readFile, stat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+import { GSD } from './index.js';
+import { InitRunner } from './init-runner.js';
+import { GSDTools } from './gsd-tools.js';
+import { GSDEventStream } from './event-stream.js';
+import { GSDEventType, PhaseStepType } from './types.js';
+import type { GSDEvent, PhaseRunnerResult, RoadmapAnalysis } from './types.js';
+
+// ─── CLI availability check ─────────────────────────────────────────────────
+
+let cliAvailable = false;
+try {
+  execSync('which claude', { stdio: 'ignore' });
+  cliAvailable = true;
+} catch {
+  cliAvailable = false;
+}
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const sdkPromptsDir = join(__dirname, '..', 'prompts');
+const GSD_TOOLS_PATH = join(homedir(), '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs');
+
+// ─── Lifecycle step ordering for monotonicity check ──────────────────────────
+
+const STEP_ORDER: Record<string, number> = {
+  [PhaseStepType.Discuss]: 0,
+  [PhaseStepType.Research]: 1,
+  [PhaseStepType.Plan]: 2,
+  [PhaseStepType.PlanCheck]: 3,
+  [PhaseStepType.Execute]: 4,
+  [PhaseStepType.Verify]: 5,
+  [PhaseStepType.Advance]: 6,
+};
+
+// ─── Test suite ──────────────────────────────────────────────────────────────
+
+describe.skipIf(!cliAvailable)('E2E Lifecycle: InitRunner → GSD.runPhase() full lifecycle', () => {
+  let tmpDir: string;
+  let initSuccess: boolean = false;
+  let phase1Number: string | null = null;
+  let tools: GSDTools;
+
+  // ── Bootstrap: create temp dir, git init, run InitRunner ──────────────
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-sdk-lifecycle-e2e-'));
+
+    // Git init (required by InitRunner and phase lifecycle)
+    execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'ignore' });
+
+    tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: GSD_TOOLS_PATH,
+      timeoutMs: 30_000,
+    });
+
+    // Run InitRunner to bootstrap the project
+    const initEventStream = new GSDEventStream();
+    const initRunner = new InitRunner({
+      projectDir: tmpDir,
+      tools,
+      eventStream: initEventStream,
+      config: {
+        maxBudgetPerSession: 1.0,
+        maxTurnsPerSession: 15,
+      },
+      sdkPromptsDir,
+    });
+
+    const initResult = await initRunner.run('Build a CLI tool that converts Celsius to Fahrenheit');
+
+    // Mark init as successful if the pipeline progressed enough
+    const completedSteps = initResult.steps.filter(s => s.success);
+    initSuccess = initResult.success || completedSteps.length >= 3;
+
+    // Discover the first phase number via roadmapAnalyze
+    if (initSuccess) {
+      try {
+        const analysis: RoadmapAnalysis = await tools.roadmapAnalyze();
+        if (analysis.phases && analysis.phases.length > 0) {
+          // Sort by phase number and take the first
+          const sorted = [...analysis.phases].sort(
+            (a, b) => parseFloat(a.number) - parseFloat(b.number),
+          );
+          phase1Number = sorted[0]!.number;
+        }
+      } catch {
+        // If roadmap analyze fails, try scanning the phases dir directly
+        try {
+          const phasesDir = join(tmpDir, '.planning', 'phases');
+          const entries = await readdir(phasesDir);
+          const phaseEntries = entries
+            .filter(e => /^\d+/.test(e))
+            .sort();
+          if (phaseEntries.length > 0) {
+            // Extract the phase number (everything before the first dash)
+            const match = phaseEntries[0]!.match(/^(\d+)/);
+            if (match) {
+              phase1Number = match[1]!;
+            }
+          }
+        } catch {
+          // No phases dir — init didn't create one
+        }
+      }
+    }
+  }, 600_000); // 10 min for init
+
+  afterAll(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  // ── Main lifecycle test ───────────────────────────────────────────────
+
+  it('GSD.runPhase() drives Phase 1 through the full lifecycle without human intervention', async () => {
+    // If init failed, skip — can't test lifecycle without a bootstrapped project
+    if (!initSuccess) {
+      console.warn('Skipping lifecycle test: InitRunner did not bootstrap successfully');
+      return;
+    }
+
+    // Verify ROADMAP.md exists and contains at least one phase
+    const roadmapPath = join(tmpDir, '.planning', 'ROADMAP.md');
+    const roadmapStat = await stat(roadmapPath).catch(() => null);
+    expect(roadmapStat).not.toBeNull();
+
+    const roadmapContent = await readFile(roadmapPath, 'utf-8');
+    expect(roadmapContent.length).toBeGreaterThan(0);
+
+    // Verify we discovered a phase number
+    expect(phase1Number).not.toBeNull();
+
+    // Verify the phase exists via initPhaseOp
+    const phaseOp = await tools.initPhaseOp(phase1Number!);
+    expect(phaseOp.phase_found).toBe(true);
+
+    // Collect all events during the phase lifecycle
+    const events: GSDEvent[] = [];
+
+    // Construct GSD with autoMode: true
+    const gsd = new GSD({
+      projectDir: tmpDir,
+      autoMode: true,
+    });
+    gsd.onEvent((e: GSDEvent) => events.push(e));
+
+    // Run the discovered first phase with tight budget to minimize cost
+    const result: PhaseRunnerResult = await gsd.runPhase(phase1Number!, {
+      maxTurnsPerStep: 10,
+      maxBudgetPerStep: 0.50,
+    });
+
+    // ── Assert: result.phaseNumber matches the discovered phase ──
+    expect(result.phaseNumber).toBe(phase1Number);
+
+    // ── Assert: result.phaseName is non-empty ──
+    expect(result.phaseName).toBeTruthy();
+    expect(result.phaseName.length).toBeGreaterThan(0);
+
+    // ── Assert: at least one lifecycle step was attempted ──
+    expect(result.steps.length).toBeGreaterThanOrEqual(1);
+
+    // ── Assert: events include PhaseStart ──
+    const phaseStartEvents = events.filter(e => e.type === GSDEventType.PhaseStart);
+    expect(phaseStartEvents.length).toBe(1);
+    const phaseStart = phaseStartEvents[0]!;
+    if (phaseStart.type === GSDEventType.PhaseStart) {
+      expect(phaseStart.phaseNumber).toBe(phase1Number);
+      expect(phaseStart.phaseName).toBeTruthy();
+    }
+
+    // ── Assert: events include PhaseComplete ──
+    const phaseCompleteEvents = events.filter(e => e.type === GSDEventType.PhaseComplete);
+    expect(phaseCompleteEvents.length).toBe(1);
+    const phaseComplete = phaseCompleteEvents[0]!;
+    if (phaseComplete.type === GSDEventType.PhaseComplete) {
+      expect(phaseComplete.phaseNumber).toBe(phase1Number);
+      expect(typeof phaseComplete.totalCostUsd).toBe('number');
+      expect(typeof phaseComplete.totalDurationMs).toBe('number');
+    }
+
+    // ── Assert: PhaseStepStart events show step progression ──
+    const stepStartEvents = events.filter(
+      (e): e is Extract<GSDEvent, { type: GSDEventType.PhaseStepStart }> =>
+        e.type === GSDEventType.PhaseStepStart,
+    );
+    expect(stepStartEvents.length).toBeGreaterThanOrEqual(1);
+
+    // Extract the step types in order
+    const stepTypesInOrder = stepStartEvents.map(e => e.step);
+
+    // Verify monotonic ordering: each step type should have an index >= previous
+    // Note: gap-closure can re-run plan+execute after verify, so we allow
+    // monotonicity to break only when verify triggers gap closure.
+    // For this tight-budget test, full gap closure is unlikely — check basic ordering.
+    let lastMaxOrder = -1;
+    for (const stepType of stepTypesInOrder) {
+      const order = STEP_ORDER[stepType] ?? -1;
+      // Track the high-water mark — steps should generally progress forward
+      if (order >= lastMaxOrder) {
+        lastMaxOrder = order;
+      }
+    }
+    // At least progressed past discuss (order 0) into real work
+    expect(lastMaxOrder).toBeGreaterThanOrEqual(1);
+
+    // ── Assert: at least one step has planResults with cost > 0 (real Agent SDK work) ──
+    const stepsWithCost = result.steps.filter(s => {
+      if (!s.planResults) return false;
+      return s.planResults.some(pr => pr.totalCostUsd > 0);
+    });
+    // At least one step should have incurred real cost (proves Agent SDK was invoked)
+    expect(stepsWithCost.length).toBeGreaterThanOrEqual(1);
+
+    // ── Assert: result cost and duration are tracked ──
+    expect(typeof result.totalCostUsd).toBe('number');
+    expect(result.totalDurationMs).toBeGreaterThan(0);
+
+    // ── Assert: each step result is properly structured ──
+    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');
+    }
+
+    // ── Assert: PhaseStepComplete events match step results ──
+    const stepCompleteEvents = events.filter(
+      (e): e is Extract<GSDEvent, { type: GSDEventType.PhaseStepComplete }> =>
+        e.type === GSDEventType.PhaseStepComplete,
+    );
+    // At least as many complete events as step results
+    expect(stepCompleteEvents.length).toBeGreaterThanOrEqual(result.steps.length);
+  }, 900_000); // 15 minute timeout: init (~4 min) + phase lifecycle (~10 min)
+});