@bhargavvc/sdd-cc 1.35.0 → 1.42.4

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?: {
+    sddInstallDir?: string;
+    agentsDir?: string;
+    projectAgentsDir?: string;
+    sdkPromptsDir?: string;
+    projectDir?: string;
+  }) {
+    const sddInstallDir = options?.sddInstallDir ?? resolveLegacyInstallDir();
+    this.workflowsDir = join(sddInstallDir, 'workflows');
+    this.agentsDir = options?.agentsDir ?? join(sddInstallDir, '..', '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 SDD 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 SDD 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-types.test.ts

@@ -0,0 +1,421 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SDDTools, SDDToolsError } from './sdd-tools.js';
+import {
+  PhaseStepType,
+  SDDEventType,
+  PhaseType,
+  type PhaseOpInfo,
+  type PhaseStepResult,
+  type PhaseRunnerResult,
+  type HumanGateCallbacks,
+  type PhaseRunnerOptions,
+  type SDDPhaseStartEvent,
+  type SDDPhaseStepStartEvent,
+  type SDDPhaseStepCompleteEvent,
+  type SDDPhaseCompleteEvent,
+} from './types.js';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('Phase lifecycle types', () => {
+  // ─── PhaseStepType enum ────────────────────────────────────────────────
+
+  describe('PhaseStepType', () => {
+    it('has all expected step values', () => {
+      expect(PhaseStepType.Discuss).toBe('discuss');
+      expect(PhaseStepType.Research).toBe('research');
+      expect(PhaseStepType.Plan).toBe('plan');
+      expect(PhaseStepType.Execute).toBe('execute');
+      expect(PhaseStepType.Verify).toBe('verify');
+      expect(PhaseStepType.Advance).toBe('advance');
+    });
+
+    it('has exactly 7 members', () => {
+      const values = Object.values(PhaseStepType);
+      expect(values).toHaveLength(7);
+    });
+  });
+
+  // ─── SDDEventType phase lifecycle values ───────────────────────────────
+
+  describe('SDDEventType phase lifecycle events', () => {
+    it('includes PhaseStart', () => {
+      expect(SDDEventType.PhaseStart).toBe('phase_start');
+    });
+
+    it('includes PhaseStepStart', () => {
+      expect(SDDEventType.PhaseStepStart).toBe('phase_step_start');
+    });
+
+    it('includes PhaseStepComplete', () => {
+      expect(SDDEventType.PhaseStepComplete).toBe('phase_step_complete');
+    });
+
+    it('includes PhaseComplete', () => {
+      expect(SDDEventType.PhaseComplete).toBe('phase_complete');
+    });
+  });
+
+  // ─── PhaseOpInfo shape validation ──────────────────────────────────────
+
+  describe('PhaseOpInfo interface', () => {
+    it('accepts a valid phase-op output object', () => {
+      const info: PhaseOpInfo = {
+        phase_found: true,
+        phase_dir: '.planning/phases/05-Skill-Scaffolding',
+        phase_number: '5',
+        phase_name: 'Skill Scaffolding',
+        phase_slug: 'skill-scaffolding',
+        padded_phase: '05',
+        has_research: false,
+        has_context: false,
+        has_plans: false,
+        has_verification: false,
+        plan_count: 0,
+        roadmap_exists: true,
+        planning_exists: true,
+        commit_docs: true,
+        context_path: '.planning/phases/05-Skill-Scaffolding/CONTEXT.md',
+        research_path: '.planning/phases/05-Skill-Scaffolding/RESEARCH.md',
+      };
+
+      expect(info.phase_found).toBe(true);
+      expect(info.phase_number).toBe('5');
+      expect(info.plan_count).toBe(0);
+      expect(info.has_context).toBe(false);
+    });
+
+    it('matches the documented init phase-op JSON shape', () => {
+      // Simulate parsing JSON from sdd-tools.cjs
+      const raw = JSON.parse(JSON.stringify({
+        phase_found: true,
+        phase_dir: '.planning/phases/03-Auth',
+        phase_number: '3',
+        phase_name: 'Auth',
+        phase_slug: 'auth',
+        padded_phase: '03',
+        has_research: true,
+        has_context: true,
+        has_plans: true,
+        has_verification: false,
+        plan_count: 2,
+        roadmap_exists: true,
+        planning_exists: true,
+        commit_docs: true,
+        context_path: '.planning/phases/03-Auth/CONTEXT.md',
+        research_path: '.planning/phases/03-Auth/RESEARCH.md',
+      }));
+
+      const info = raw as PhaseOpInfo;
+      expect(info.phase_found).toBe(true);
+      expect(info.has_plans).toBe(true);
+      expect(info.plan_count).toBe(2);
+      expect(typeof info.phase_dir).toBe('string');
+      expect(typeof info.padded_phase).toBe('string');
+    });
+  });
+
+  // ─── Phase result types ────────────────────────────────────────────────
+
+  describe('PhaseStepResult', () => {
+    it('can represent a successful step', () => {
+      const result: PhaseStepResult = {
+        step: PhaseStepType.Research,
+        success: true,
+        durationMs: 5000,
+      };
+      expect(result.success).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    it('can represent a failed step with error', () => {
+      const result: PhaseStepResult = {
+        step: PhaseStepType.Execute,
+        success: false,
+        durationMs: 12000,
+        error: 'Session timed out',
+        planResults: [],
+      };
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Session timed out');
+    });
+  });
+
+  describe('PhaseRunnerResult', () => {
+    it('can represent a complete phase run', () => {
+      const result: PhaseRunnerResult = {
+        phaseNumber: '3',
+        phaseName: 'Auth',
+        steps: [
+          { step: PhaseStepType.Research, success: true, durationMs: 5000 },
+          { step: PhaseStepType.Plan, success: true, durationMs: 3000 },
+          { step: PhaseStepType.Execute, success: true, durationMs: 60000 },
+        ],
+        success: true,
+        totalCostUsd: 1.5,
+        totalDurationMs: 68000,
+      };
+      expect(result.steps).toHaveLength(3);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('HumanGateCallbacks', () => {
+    it('accepts an object with all optional callbacks', () => {
+      const callbacks: HumanGateCallbacks = {
+        onDiscussApproval: async () => 'approve',
+        onVerificationReview: async () => 'accept',
+        onBlockerDecision: async () => 'retry',
+      };
+      expect(callbacks.onDiscussApproval).toBeDefined();
+    });
+
+    it('accepts an empty object (all callbacks optional)', () => {
+      const callbacks: HumanGateCallbacks = {};
+      expect(callbacks.onDiscussApproval).toBeUndefined();
+    });
+  });
+
+  describe('PhaseRunnerOptions', () => {
+    it('accepts full options', () => {
+      const options: PhaseRunnerOptions = {
+        callbacks: {},
+        maxBudgetPerStep: 3.0,
+        maxTurnsPerStep: 30,
+        model: 'claude-sonnet-4-6',
+      };
+      expect(options.maxBudgetPerStep).toBe(3.0);
+    });
+
+    it('accepts empty options (all fields optional)', () => {
+      const options: PhaseRunnerOptions = {};
+      expect(options.callbacks).toBeUndefined();
+    });
+  });
+
+  // ─── Phase lifecycle event interfaces ──────────────────────────────────
+
+  describe('Phase lifecycle event interfaces', () => {
+    it('SDDPhaseStartEvent has correct shape', () => {
+      const event: SDDPhaseStartEvent = {
+        type: SDDEventType.PhaseStart,
+        timestamp: new Date().toISOString(),
+        sessionId: 'test-session',
+        phaseNumber: '3',
+        phaseName: 'Auth',
+      };
+      expect(event.type).toBe('phase_start');
+      expect(event.phaseNumber).toBe('3');
+    });
+
+    it('SDDPhaseStepStartEvent has correct shape', () => {
+      const event: SDDPhaseStepStartEvent = {
+        type: SDDEventType.PhaseStepStart,
+        timestamp: new Date().toISOString(),
+        sessionId: 'test-session',
+        phaseNumber: '3',
+        step: PhaseStepType.Research,
+      };
+      expect(event.type).toBe('phase_step_start');
+      expect(event.step).toBe('research');
+    });
+
+    it('SDDPhaseStepCompleteEvent has correct shape', () => {
+      const event: SDDPhaseStepCompleteEvent = {
+        type: SDDEventType.PhaseStepComplete,
+        timestamp: new Date().toISOString(),
+        sessionId: 'test-session',
+        phaseNumber: '3',
+        step: PhaseStepType.Execute,
+        success: true,
+        durationMs: 45000,
+      };
+      expect(event.type).toBe('phase_step_complete');
+      expect(event.success).toBe(true);
+    });
+
+    it('SDDPhaseStepCompleteEvent can include error', () => {
+      const event: SDDPhaseStepCompleteEvent = {
+        type: SDDEventType.PhaseStepComplete,
+        timestamp: new Date().toISOString(),
+        sessionId: 'test-session',
+        phaseNumber: '3',
+        step: PhaseStepType.Verify,
+        success: false,
+        durationMs: 2000,
+        error: 'Verification failed',
+      };
+      expect(event.error).toBe('Verification failed');
+    });
+
+    it('SDDPhaseCompleteEvent has correct shape', () => {
+      const event: SDDPhaseCompleteEvent = {
+        type: SDDEventType.PhaseComplete,
+        timestamp: new Date().toISOString(),
+        sessionId: 'test-session',
+        phaseNumber: '3',
+        phaseName: 'Auth',
+        success: true,
+        totalCostUsd: 2.5,
+        totalDurationMs: 120000,
+        stepsCompleted: 5,
+      };
+      expect(event.type).toBe('phase_complete');
+      expect(event.stepsCompleted).toBe(5);
+    });
+  });
+});
+
+// ─── SDDTools typed methods ──────────────────────────────────────────────────
+
+describe('SDDTools typed methods', () => {
+  let tmpDir: string;
+  let fixtureDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `sdd-tools-phase-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtureDir = join(tmpDir, 'fixtures');
+    await mkdir(fixtureDir, { recursive: true });
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  async function createScript(name: string, code: string): Promise<string> {
+    const scriptPath = join(fixtureDir, name);
+    await writeFile(scriptPath, code, { mode: 0o755 });
+    return scriptPath;
+  }
+
+  describe('initPhaseOp()', () => {
+    it('returns typed PhaseOpInfo from sdd-tools output', async () => {
+      const mockOutput: PhaseOpInfo = {
+        phase_found: true,
+        phase_dir: '.planning/phases/05-Skill-Scaffolding',
+        phase_number: '5',
+        phase_name: 'Skill Scaffolding',
+        phase_slug: 'skill-scaffolding',
+        padded_phase: '05',
+        has_research: false,
+        has_context: true,
+        has_plans: true,
+        has_verification: false,
+        plan_count: 3,
+        roadmap_exists: true,
+        planning_exists: true,
+        commit_docs: true,
+        context_path: '.planning/phases/05-Skill-Scaffolding/CONTEXT.md',
+        research_path: '.planning/phases/05-Skill-Scaffolding/RESEARCH.md',
+      };
+
+      const scriptPath = await createScript(
+        'init-phase-op.cjs',
+        `
+        const args = process.argv.slice(2);
+        // Script receives: init phase-op 5 --raw
+        if (args[0] === 'init' && args[1] === 'phase-op' && args[2] === '5') {
+          process.stdout.write(JSON.stringify(${JSON.stringify(mockOutput)}));
+        } else {
+          process.stderr.write('unexpected args: ' + args.join(' '));
+          process.exit(1);
+        }
+        `,
+      );
+
+      const tools = new SDDTools({ projectDir: tmpDir, sddToolsPath: scriptPath, preferNativeQuery: false });
+      const result = await tools.initPhaseOp('5');
+
+      expect(result.phase_found).toBe(true);
+      expect(result.phase_number).toBe('5');
+      expect(result.phase_name).toBe('Skill Scaffolding');
+      expect(result.plan_count).toBe(3);
+      expect(result.has_context).toBe(true);
+      expect(result.has_plans).toBe(true);
+      expect(result.context_path).toContain('CONTEXT.md');
+    });
+
+    it('calls exec with correct args (init phase-op <N>)', async () => {
+      const scriptPath = await createScript(
+        'init-phase-op-args.cjs',
+        `
+        const args = process.argv.slice(2);
+        process.stdout.write(JSON.stringify({ received_args: args }));
+        `,
+      );
+
+      const tools = new SDDTools({ projectDir: tmpDir, sddToolsPath: scriptPath, preferNativeQuery: false });
+      const result = await tools.initPhaseOp('7') as { received_args: string[] };
+
+      expect(result.received_args).toContain('init');
+      expect(result.received_args).toContain('phase-op');
+      expect(result.received_args).toContain('7');
+      // exec() no longer appends --raw (only execRaw does)
+      expect(result.received_args).not.toContain('--raw');
+    });
+  });
+
+  describe('configGet()', () => {
+    it('returns string value from sdd-tools config', async () => {
+      const scriptPath = await createScript(
+        'config-get.cjs',
+        `
+        const args = process.argv.slice(2);
+        if (args[0] === 'config-get' && args[1] === 'model_profile') {
+          process.stdout.write(JSON.stringify('balanced'));
+        } else {
+          process.exit(1);
+        }
+        `,
+      );
+
+      const tools = new SDDTools({ projectDir: tmpDir, sddToolsPath: scriptPath, preferNativeQuery: false });
+      const result = await tools.configGet('model_profile');
+
+      expect(result).toBe('balanced');
+    });
+
+    it('returns null when key not found', async () => {
+      const scriptPath = await createScript(
+        'config-get-null.cjs',
+        `
+        const args = process.argv.slice(2);
+        if (args[0] === 'config-get' && args[1] === 'nonexistent_key') {
+          process.stdout.write('null');
+        } else {
+          process.exit(1);
+        }
+        `,
+      );
+
+      const tools = new SDDTools({ projectDir: tmpDir, sddToolsPath: scriptPath, preferNativeQuery: false });
+      const result = await tools.configGet('nonexistent_key');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('stateBeginPhase()', () => {
+    it('calls state begin-phase with correct args', async () => {
+      const scriptPath = await createScript(
+        'state-begin-phase.cjs',
+        `
+        const args = process.argv.slice(2);
+        if (args[0] === 'state' && args[1] === 'begin-phase' && args[2] === '--phase' && args[3] === '3') {
+          process.stdout.write('ok');
+        } else {
+          process.stderr.write('unexpected args: ' + args.join(' '));
+          process.exit(1);
+        }
+        `,
+      );
+
+      const tools = new SDDTools({ projectDir: tmpDir, sddToolsPath: scriptPath, preferNativeQuery: false });
+      const result = await tools.stateBeginPhase('3');
+
+      expect(result).toBe('ok');
+    });
+  });
+});