@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdk/src/golden/init-golden-normalize.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalize `init quick` payloads for golden parity: CJS runs in a subprocess with a
+ * different clock than the in-process SDK, so time-derived fields cannot match exactly.
+ */
+
+/** Keys derived from `Date` / `quick_id` generation (init.cjs cmdInitQuick). */
+export const INIT_QUICK_VOLATILE_KEYS = ['quick_id', 'timestamp', 'branch_name', 'task_dir'] as const;
+
+export function omitInitQuickVolatile(data: Record<string, unknown>): Record<string, unknown> {
+  const o = { ...data };
+  for (const k of INIT_QUICK_VOLATILE_KEYS) {
+    delete o[k];
+  }
+  return o;
+}

package/sdk/src/golden/read-only-golden-rows.ts

@@ -0,0 +1,77 @@
+/**
+ * Read-only subprocess golden rows: SDK `registry.dispatch` vs `sdd-tools.cjs` JSON on stdout.
+ * Imported by `read-only-parity.integration.test.ts` and `golden-policy.ts` coverage accounting.
+ */
+
+export type JsonParityRow = {
+  canonical: string;
+  sdkArgs: string[];
+  cjs: string;
+  cjsArgs: string[];
+};
+
+/** Repo-relative fixtures (cwd = sdd repo root). */
+export const GOLDEN_PLAN = '.planning/phases/09-foundation-and-test-infrastructure/09-01-PLAN.md';
+
+/**
+ * Strict `toEqual` JSON parity rows verified on this repository.
+ * (Expand as more handlers are aligned with `sdd-tools.cjs`.)
+ */
+export const READ_ONLY_JSON_PARITY_ROWS: JsonParityRow[] = [
+  { canonical: 'resolve-model', sdkArgs: ['sdd-planner'], cjs: 'resolve-model', cjsArgs: ['sdd-planner'] },
+  { canonical: 'phase-plan-index', sdkArgs: ['9'], cjs: 'phase-plan-index', cjsArgs: ['9'] },
+  { canonical: 'roadmap.get-phase', sdkArgs: ['9'], cjs: 'roadmap', cjsArgs: ['get-phase', '9'] },
+  { canonical: 'list.todos', sdkArgs: [], cjs: 'list-todos', cjsArgs: [] },
+  { canonical: 'phase.next-decimal', sdkArgs: ['9'], cjs: 'phase', cjsArgs: ['next-decimal', '9'] },
+  { canonical: 'phases.list', sdkArgs: [], cjs: 'phases', cjsArgs: ['list'] },
+  { canonical: 'verify.summary', sdkArgs: [GOLDEN_PLAN], cjs: 'verify-summary', cjsArgs: [GOLDEN_PLAN] },
+  { canonical: 'verify.path-exists', sdkArgs: ['.planning/STATE.md'], cjs: 'verify-path-exists', cjsArgs: ['.planning/STATE.md'] },
+  { canonical: 'verify.artifacts', sdkArgs: [GOLDEN_PLAN], cjs: 'verify', cjsArgs: ['artifacts', GOLDEN_PLAN] },
+  { canonical: 'websearch', sdkArgs: ['typescript', '--limit', '1'], cjs: 'websearch', cjsArgs: ['typescript', '--limit', '1'] },
+  { canonical: 'workstream.get', sdkArgs: ['default'], cjs: 'workstream', cjsArgs: ['get', 'default'] },
+  { canonical: 'workstream.list', sdkArgs: [], cjs: 'workstream', cjsArgs: ['list'] },
+  { canonical: 'workstream.status', sdkArgs: ['default'], cjs: 'workstream', cjsArgs: ['status', 'default'] },
+  { canonical: 'learnings.list', sdkArgs: [], cjs: 'learnings', cjsArgs: ['list'] },
+  { canonical: 'intel.status', sdkArgs: [], cjs: 'intel', cjsArgs: ['status'] },
+  { canonical: 'intel.diff', sdkArgs: [], cjs: 'intel', cjsArgs: ['diff'] },
+  { canonical: 'intel.validate', sdkArgs: [], cjs: 'intel', cjsArgs: ['validate'] },
+  { canonical: 'intel.query', sdkArgs: ['sdd'], cjs: 'intel', cjsArgs: ['query', 'sdd'] },
+  {
+    canonical: 'intel.extract-exports',
+    sdkArgs: ['sdk/src/query/utils.ts'],
+    cjs: 'intel',
+    cjsArgs: ['extract-exports', 'sdk/src/query/utils.ts'],
+  },
+  { canonical: 'init.list-workspaces', sdkArgs: [], cjs: 'init', cjsArgs: ['list-workspaces'] },
+  { canonical: 'agent-skills', sdkArgs: [], cjs: 'agent-skills', cjsArgs: [] },
+  { canonical: 'scan-sessions', sdkArgs: ['--json'], cjs: 'scan-sessions', cjsArgs: ['--json'] },
+  { canonical: 'stats.json', sdkArgs: [], cjs: 'stats', cjsArgs: ['json'] },
+  { canonical: 'todo.match-phase', sdkArgs: ['9'], cjs: 'todo', cjsArgs: ['match-phase', '9'] },
+  { canonical: 'verify.key-links', sdkArgs: [GOLDEN_PLAN], cjs: 'verify', cjsArgs: ['key-links', GOLDEN_PLAN] },
+  { canonical: 'verify.schema-drift', sdkArgs: ['9'], cjs: 'verify', cjsArgs: ['schema-drift', '9'] },
+  { canonical: 'state-snapshot', sdkArgs: [], cjs: 'state-snapshot', cjsArgs: [] },
+
+  { canonical: 'history.digest', sdkArgs: [], cjs: 'history-digest', cjsArgs: [] },
+  { canonical: 'audit-uat', sdkArgs: [], cjs: 'audit-uat', cjsArgs: [] },
+  { canonical: 'skill-manifest', sdkArgs: [], cjs: 'skill-manifest', cjsArgs: [] },
+  { canonical: 'validate.agents', sdkArgs: [], cjs: 'validate', cjsArgs: ['agents'] },
+  {
+    canonical: 'uat.render-checkpoint',
+    sdkArgs: ['--file', 'sdk/src/golden/fixtures/uat-render-checkpoint-sample.md'],
+    cjs: 'uat',
+    cjsArgs: ['render-checkpoint', '--file', 'sdk/src/golden/fixtures/uat-render-checkpoint-sample.md'],
+  },
+];
+
+/** Canonicals from JSON rows plus special-case subprocess tests in read-only-parity integration. */
+export function readOnlyGoldenCanonicals(): Set<string> {
+  const s = new Set<string>(READ_ONLY_JSON_PARITY_ROWS.map((r) => r.canonical));
+  s.add('verify.commits');
+  s.add('config-path');
+  s.add('state.json');
+  s.add('state.load');
+  s.add('audit-open');
+  s.add('state.get');
+  s.add('summary.extract');
+  return s;
+}

package/sdk/src/golden/read-only-parity.integration.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Read-only subprocess golden checks (SDK vs sdd-tools.cjs JSON).
+ * Row data: `read-only-golden-rows.ts`. Policy: `golden-policy.ts`, `QUERY-HANDLERS.md`.
+ */
+import { describe, it, expect } from 'vitest';
+import { captureSddToolsOutput, captureSddToolsStdout } from './capture.js';
+import { createRegistry } from '../query/index.js';
+import { resolve, dirname, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { READ_ONLY_JSON_PARITY_ROWS } from './read-only-golden-rows.js';
+
+const STABLE_JSON_PARITY_ROWS = READ_ONLY_JSON_PARITY_ROWS.filter(
+  (row) => row.canonical !== 'scan-sessions' && row.canonical !== 'audit-uat',
+);
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..', '..', '..');
+
+describe('Read-only golden parity (JSON toEqual)', () => {
+  it.each(STABLE_JSON_PARITY_ROWS)('$canonical matches sdd-tools.cjs JSON', async (row) => {
+
+    const sddOutput = await captureSddToolsOutput(row.cjs, row.cjsArgs, REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch(row.canonical, row.sdkArgs, REPO_ROOT);
+    expect(sdkResult.data).toEqual(sddOutput);
+  });
+});
+
+describe('config-path (plain stdout vs SDK { path })', () => {
+  it('SDK path matches sdd-tools.cjs plain-text stdout', async () => {
+    const out = await captureSddToolsStdout('config-path', [], REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('config-path', [], REPO_ROOT);
+    const data = sdkResult.data as { path?: string };
+    expect(data.path).toBeDefined();
+    expect(normalize(data.path!.trim())).toBe(normalize(out.trim()));
+  });
+});
+
+describe('audit-open golden parity (excluding scanned_at)', () => {
+  it('SDK JSON matches sdd-tools.cjs except volatile scanned_at', async () => {
+    const sddOutput = await captureSddToolsOutput('audit-open', ['--json'], REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('audit-open', ['--json'], REPO_ROOT);
+    const strip = (d: unknown): Record<string, unknown> => {
+      const o = { ...(d as Record<string, unknown>) };
+      delete o.scanned_at;
+      delete o.has_scan_errors;
+      return o;
+    };
+    expect(strip(sdkResult.data)).toEqual(strip(sddOutput));
+  });
+});
+
+describe('state.json golden parity (excluding last_updated)', () => {
+  it('SDK rebuilt frontmatter matches sdd-tools.cjs except volatile last_updated', async () => {
+    const sddOutput = await captureSddToolsOutput('state', ['json'], REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('state.json', [], REPO_ROOT);
+    const strip = (d: unknown): Record<string, unknown> => {
+      const o = { ...(d as Record<string, unknown>) };
+      delete o.last_updated;
+      return o;
+    };
+    expect(strip(sdkResult.data)).toEqual(strip(sddOutput));
+  });
+});
+
+describe('summary.extract golden parity (with array-of-objects fix)', () => {
+  it('SDK JSON matches sdd-tools.cjs except for intentional array-of-objects parsing fix', async () => {
+    const sddOutput = await captureSddToolsOutput('summary-extract', ['sdk/src/golden/fixtures/summary-extract-sample.md'], REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('summary.extract', ['sdk/src/golden/fixtures/summary-extract-sample.md'], REPO_ROOT);
+    
+    // The SDK correctly parses array-of-objects, whereas CJS parses them as strings.
+    // Patch the CJS output to reflect the CodeRabbit bugfix.
+    const patchedGsd = JSON.parse(JSON.stringify(sddOutput));
+    if (patchedGsd.tech_added && Array.isArray(patchedGsd.tech_added)) {
+      patchedGsd.tech_added = patchedGsd.tech_added.map((t: any) => 
+        t === 'name: typescript' ? { name: 'typescript' } : t
+      );
+    }
+    
+    expect(sdkResult.data).toEqual(patchedGsd);
+  });
+});
+
+describe('state.load golden parity', () => {
+  it('SDK load payload matches sdd-tools.cjs state load', async () => {
+    const sddOutput = await captureSddToolsOutput('state', ['load'], REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('state.load', [], REPO_ROOT);
+    expect(sdkResult.data).toEqual(sddOutput);
+  });
+});
+
+describe('state.get golden parity', () => {
+  it('matches full STATE.md when no field (same as `state get` with no section)', async ({ skip }) => {
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('state.get', [], REPO_ROOT);
+    // Repo may not have .planning/STATE.md; skip parity in that case.
+    if ((sdkResult.data as Record<string, unknown>)?.error === 'STATE.md not found') skip();
+    const sddOutput = await captureSddToolsOutput('state', ['get'], REPO_ROOT);
+    expect(sdkResult.data).toEqual(sddOutput);
+  });
+
+  it('matches single frontmatter field when `state get <field>`', async ({ skip }) => {
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('state.get', ['milestone'], REPO_ROOT);
+    if ((sdkResult.data as Record<string, unknown>)?.error === 'STATE.md not found') skip();
+    const sddOutput = await captureSddToolsOutput('state', ['get', 'milestone'], REPO_ROOT);
+    expect(sdkResult.data).toEqual(sddOutput);
+  });
+});
+
+describe('verify.commits golden parity', () => {
+  it('SDK output matches sdd-tools.cjs for two SHAs', async () => {
+    const revs = execSync('git rev-list --max-count=2 HEAD', { cwd: REPO_ROOT, encoding: 'utf-8' })
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+    if (revs.length < 2) {
+      throw new Error('verify.commits parity requires at least 2 commits in checkout history');
+    }
+    const b = revs[0];
+    const a = revs[1];
+    const sddOutput = await captureSddToolsOutput('verify', ['commits', a, b], REPO_ROOT);
+    const registry = createRegistry();
+    const sdkResult = await registry.dispatch('verify.commits', [a, b], REPO_ROOT);
+    expect(sdkResult.data).toEqual(sddOutput);
+  });
+});

package/sdk/src/golden/registry-canonical-commands.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical registry command strings for golden parity — one primary name per unique
+ * native handler (dedupes dotted vs space-delimited aliases on the same function).
+ */
+
+import { createRegistry } from '../query/index.js';
+import type { QueryHandler } from '../query/utils.js';
+
+export function getCanonicalRegistryCommands(): string[] {
+  const registry = createRegistry();
+  const byHandler = new Map<QueryHandler, string[]>();
+  for (const cmd of registry.commands()) {
+    const h = registry.getHandler(cmd);
+    if (!h) continue;
+    const list = byHandler.get(h) ?? [];
+    list.push(cmd);
+    byHandler.set(h, list);
+  }
+  const out: string[] = [];
+  for (const cmds of byHandler.values()) {
+    cmds.sort((a, b) => a.localeCompare(b));
+    const dotted = cmds.find((c) => c.includes('.'));
+    if (dotted) {
+      out.push(dotted);
+      continue;
+    }
+    const kebab = cmds.find((c) => c.includes('-'));
+    out.push(kebab ?? cmds[0]!);
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}

package/sdk/src/index.ts

@@ -0,0 +1,352 @@
+/**
+ * SDD SDK — Public API for running SDD plans programmatically.
+ *
+ * The SDD class composes plan parsing, config loading, prompt building,
+ * and session running into a single `executePlan()` call.
+ *
+ * @example
+ * ```typescript
+ * import { SDD } from '@bhargavvc/sdk';
+ *
+ * const sdd = new SDD({ projectDir: '/path/to/project' });
+ * const result = await sdd.executePlan('.planning/phases/01-auth/01-auth-01-PLAN.md');
+ *
+ * if (result.success) {
+ *   console.log(`Plan completed in ${result.durationMs}ms, cost: $${result.totalCostUsd}`);
+ * } else {
+ *   console.error(`Plan failed: ${result.error?.messages.join(', ')}`);
+ * }
+ * ```
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+import type { SDDOptions, PlanResult, SessionOptions, SDDEvent, TransportHandler, PhaseRunnerOptions, PhaseRunnerResult, MilestoneRunnerOptions, MilestoneRunnerResult, RoadmapPhaseInfo } from './types.js';
+import { SDDEventType } from './types.js';
+import { parsePlan, parsePlanFile } from './plan-parser.js';
+import { loadConfig } from './config.js';
+import { SDDTools, resolveSddToolsPath } from './sdd-tools.js';
+import { runPlanSession } from './session-runner.js';
+import { buildExecutorPrompt, parseAgentTools } from './prompt-builder.js';
+import { SDDEventStream } from './event-stream.js';
+import { PhaseRunner } from './phase-runner.js';
+import { ContextEngine } from './context-engine.js';
+import { PromptFactory } from './phase-prompt.js';
+
+export { PlanningJournal } from './planning-journal.js';
+export type { PlanningEvent, PlanningEventActor, PlanningJournalAppendInput } from './planning-journal.js';
+export { PlanningRuntime } from './planning-runtime.js';
+
+// ─── SDD class ───────────────────────────────────────────────────────────────
+
+export class SDD {
+  private readonly projectDir: string;
+  private readonly sddToolsPath: string;
+  private readonly sessionId?: string;
+  private readonly defaultModel?: string;
+  private readonly defaultMaxBudgetUsd: number;
+  private readonly defaultMaxTurns: number;
+  private readonly autoMode: boolean;
+  private readonly workstream?: string;
+  private readonly strictSdk?: boolean;
+  private readonly allowFallbackToSubprocess?: boolean;
+  readonly eventStream: SDDEventStream;
+
+  constructor(options: SDDOptions) {
+    this.projectDir = resolve(options.projectDir);
+    this.sddToolsPath =
+      options.sddToolsPath ?? resolveSddToolsPath(this.projectDir);
+    this.sessionId = options.sessionId;
+    this.defaultModel = options.model;
+    this.defaultMaxBudgetUsd = options.maxBudgetUsd ?? 5.0;
+    this.defaultMaxTurns = options.maxTurns ?? 50;
+    this.autoMode = options.autoMode ?? false;
+    this.workstream = options.workstream;
+    this.strictSdk = options.strictSdk;
+    this.allowFallbackToSubprocess = options.allowFallbackToSubprocess;
+    this.eventStream = new SDDEventStream();
+  }
+
+  /**
+   * Execute a single SDD plan file.
+   *
+   * Reads the plan from disk, parses it, loads project config,
+   * optionally reads the agent definition, then runs a query() session.
+   *
+   * @param planPath - Path to the PLAN.md file (absolute or relative to projectDir)
+   * @param options - Per-execution overrides
+   * @returns PlanResult with cost, duration, success/error status
+   */
+  async executePlan(planPath: string, options?: SessionOptions): Promise<PlanResult> {
+    // Resolve plan path relative to project dir
+    const absolutePlanPath = resolve(this.projectDir, planPath);
+
+    // Parse the plan
+    const plan = await parsePlanFile(absolutePlanPath);
+
+    // Load project config
+    const config = await loadConfig(this.projectDir, this.workstream);
+
+    // Try to load agent definition for tool restrictions
+    const agentDef = await this.loadAgentDefinition();
+
+    // Merge defaults with per-call options
+    const sessionOptions: SessionOptions = {
+      maxTurns: options?.maxTurns ?? this.defaultMaxTurns,
+      maxBudgetUsd: options?.maxBudgetUsd ?? this.defaultMaxBudgetUsd,
+      model: options?.model ?? this.defaultModel,
+      cwd: options?.cwd ?? this.projectDir,
+      allowedTools: options?.allowedTools,
+    };
+
+    return runPlanSession(plan, config, sessionOptions, agentDef, this.eventStream, {
+      phase: undefined, // Phase context set by higher-level orchestrators
+      planName: plan.frontmatter.plan,
+    });
+  }
+
+  /**
+   * Subscribe a simple handler to receive all SDD events.
+   */
+  onEvent(handler: (event: SDDEvent) => void): void {
+    this.eventStream.on('event', handler);
+  }
+
+  /**
+   * Subscribe a transport handler to receive all SDD events.
+   * Transports provide structured onEvent/close lifecycle.
+   */
+  addTransport(handler: TransportHandler): void {
+    this.eventStream.addTransport(handler);
+  }
+
+  /**
+   * Create a SDDTools instance for state management operations.
+   */
+  createTools(): SDDTools {
+    return new SDDTools({
+      projectDir: this.projectDir,
+      sddToolsPath: this.sddToolsPath,
+      workstream: this.workstream,
+      eventStream: this.eventStream,
+      sessionId: this.sessionId,
+      strictSdk: this.strictSdk,
+      allowFallbackToSubprocess: this.allowFallbackToSubprocess,
+      onDispatchEvent: (event) => {
+        this.eventStream.emitEvent({
+          type: SDDEventType.StreamEvent,
+          timestamp: new Date().toISOString(),
+          sessionId: this.sessionId ?? '',
+          event,
+        });
+      },
+    });
+  }
+
+  /**
+   * Run a full phase lifecycle: discuss → research → plan → execute → verify → advance.
+   *
+   * Creates the necessary collaborators (SDDTools, PromptFactory, ContextEngine),
+   * loads project config, instantiates a PhaseRunner, and delegates to `runner.run()`.
+   *
+   * @param phaseNumber - The phase number to execute (e.g. "01", "02")
+   * @param options - Per-phase overrides for budget, turns, model, and callbacks
+   * @returns PhaseRunnerResult with per-step results, overall success, cost, and timing
+   */
+  async runPhase(phaseNumber: string, options?: PhaseRunnerOptions): Promise<PhaseRunnerResult> {
+    const tools = this.createTools();
+    const promptFactory = new PromptFactory({ projectDir: this.projectDir });
+    const contextEngine = new ContextEngine(this.projectDir, undefined, undefined, this.workstream);
+    const config = await loadConfig(this.projectDir, this.workstream);
+
+    // Auto mode: force auto_advance on and skip_discuss off so self-discuss kicks in
+    if (this.autoMode) {
+      config.workflow.auto_advance = true;
+      config.workflow.skip_discuss = false;
+    }
+
+    const runner = new PhaseRunner({
+      projectDir: this.projectDir,
+      tools,
+      promptFactory,
+      contextEngine,
+      eventStream: this.eventStream,
+      config,
+    });
+
+    return runner.run(phaseNumber, options);
+  }
+
+  /**
+   * Run a full milestone: discover phases, execute each incomplete one in order,
+   * re-discover after each completion to catch dynamically inserted phases.
+   *
+   * @param prompt - The user prompt describing the milestone goal
+   * @param options - Per-milestone overrides for budget, turns, model, and callbacks
+   * @returns MilestoneRunnerResult with per-phase results, overall success, cost, and timing
+   */
+  async run(prompt: string, options?: MilestoneRunnerOptions): Promise<MilestoneRunnerResult> {
+    const tools = this.createTools();
+    const startTime = Date.now();
+    const phaseResults: PhaseRunnerResult[] = [];
+    let success = true;
+
+    // Discover initial phases
+    const initialAnalysis = await tools.roadmapAnalyze();
+    const incompletePhases = this.filterAndSortPhases(initialAnalysis.phases);
+
+    // Emit MilestoneStart
+    this.eventStream.emitEvent({
+      type: SDDEventType.MilestoneStart,
+      timestamp: new Date().toISOString(),
+      sessionId: `milestone-${Date.now()}`,
+      phaseCount: incompletePhases.length,
+      prompt,
+    });
+
+    // Loop through phases, re-discovering after each completion
+    let currentPhases = incompletePhases;
+
+    while (currentPhases.length > 0) {
+      const phase = currentPhases[0];
+
+      try {
+        const result = await this.runPhase(phase.number, options);
+        phaseResults.push(result);
+
+        if (!result.success) {
+          success = false;
+          break;
+        }
+
+        // Notify callback if present; stop if requested
+        if (options?.onPhaseComplete) {
+          const verdict = await options.onPhaseComplete(result, phase);
+          if (verdict === 'stop') {
+            break;
+          }
+        }
+
+        // Re-discover phases to catch dynamically inserted ones
+        const updatedAnalysis = await tools.roadmapAnalyze();
+        currentPhases = this.filterAndSortPhases(updatedAnalysis.phases);
+      } catch (err) {
+        // Phase threw an unexpected error — record as failure and stop
+        phaseResults.push({
+          phaseNumber: phase.number,
+          phaseName: phase.phase_name,
+          steps: [],
+          success: false,
+          totalCostUsd: 0,
+          totalDurationMs: 0,
+        });
+        success = false;
+        break;
+      }
+    }
+
+    const totalCostUsd = phaseResults.reduce((sum, r) => sum + r.totalCostUsd, 0);
+    const totalDurationMs = Date.now() - startTime;
+
+    // Emit MilestoneComplete
+    this.eventStream.emitEvent({
+      type: SDDEventType.MilestoneComplete,
+      timestamp: new Date().toISOString(),
+      sessionId: `milestone-${Date.now()}`,
+      success,
+      totalCostUsd,
+      totalDurationMs,
+      phasesCompleted: phaseResults.filter(r => r.success).length,
+    });
+
+    return {
+      success,
+      phases: phaseResults,
+      totalCostUsd,
+      totalDurationMs,
+    };
+  }
+
+  /**
+   * Filter to incomplete phases and sort numerically.
+   * Uses parseFloat to handle decimal phase numbers (e.g. '5.1').
+   */
+  private filterAndSortPhases(phases: RoadmapPhaseInfo[]): RoadmapPhaseInfo[] {
+    return phases
+      .filter(p => !p.roadmap_complete)
+      .sort((a, b) => parseFloat(a.number) - parseFloat(b.number));
+  }
+
+  /**
+   * Load the sdd-executor agent definition if available.
+   * Falls back gracefully — returns undefined if not found.
+   */
+  private async loadAgentDefinition(): Promise<string | undefined> {
+    const paths = [
+      // Repo-local SDD installation
+      join(this.projectDir, '.claude', 'sdd', 'agents', 'sdd-executor.md'),
+      // Repo-local agents directory
+      join(this.projectDir, '.claude', 'agents', 'sdd-executor.md'),
+      // Global home directory
+      join(homedir(), '.claude', 'agents', 'sdd-executor.md'),
+      join(this.projectDir, 'agents', 'sdd-executor.md'),
+    ];
+
+    for (const p of paths) {
+      try {
+        return await readFile(p, 'utf-8');
+      } catch {
+        // Not found at this path, try next
+      }
+    }
+
+    return undefined;
+  }
+}
+
+// ─── Re-exports for advanced usage ──────────────────────────────────────────
+
+export { parsePlan, parsePlanFile } from './plan-parser.js';
+export { loadConfig } from './config.js';
+export type { SDDConfig } from './config.js';
+export { SDDTools, SDDToolsError, resolveSddToolsPath } from './sdd-tools.js';
+export { runPlanSession, runPhaseStepSession } from './session-runner.js';
+export { buildExecutorPrompt, parseAgentTools } from './prompt-builder.js';
+export type { ExecutorPromptOptions } from './prompt-builder.js';
+export * from './types.js';
+
+// S02: Event stream, context, prompt, and logging modules
+export { SDDEventStream } from './event-stream.js';
+export type { EventStreamContext } from './event-stream.js';
+export { ContextEngine, PHASE_FILE_MANIFEST } from './context-engine.js';
+export type { FileSpec } from './context-engine.js';
+export { truncateMarkdown, extractCurrentMilestone, DEFAULT_TRUNCATION_OPTIONS } from './context-truncation.js';
+export type { TruncationOptions } from './context-truncation.js';
+export { getToolsForPhase, PHASE_AGENT_MAP, PHASE_DEFAULT_TOOLS } from './tool-scoping.js';
+export { checkResearchGate } from './research-gate.js';
+export type { ResearchGateResult } from './research-gate.js';
+export { PromptFactory, extractBlock, extractSteps, PHASE_WORKFLOW_MAP } from './phase-prompt.js';
+export { SDDLogger } from './logger.js';
+export type { LogLevel, LogEntry, SDDLoggerOptions } from './logger.js';
+
+// S03: Phase lifecycle state machine
+export { PhaseRunner, PhaseRunnerError } from './phase-runner.js';
+export type { PhaseRunnerDeps, VerificationOutcome } from './phase-runner.js';
+
+// S05: Transports
+export { CLITransport } from './cli-transport.js';
+export { WSTransport } from './ws-transport.js';
+export type { WSTransportOptions } from './ws-transport.js';
+
+// Query registry argv normalization (matches `sdd-sdk query` and `SDDTools` hot path)
+export { createRegistry, normalizeQueryCommand } from './query/index.js';
+
+// Workstream utilities
+export { validateWorkstreamName, relPlanningPath } from './workstream-utils.js';
+
+// Init workflow
+export { InitRunner } from './init-runner.js';
+export type { InitRunnerDeps } from './init-runner.js';
+export type { InitConfig, InitResult, InitStepResult, InitStepName } from './types.js';