@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/src/research-gate.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect } from 'vitest';
+import { checkResearchGate } from './research-gate.js';
+
+describe('checkResearchGate', () => {
+  // ── Pass cases ──────────────────────────────────────────────────────────
+
+  it('passes when no Open Questions section exists', () => {
+    const content = `# Research
+
+## Key Findings
+Everything is clear.
+
+## Recommendations
+Use TypeScript.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes when Open Questions section has (RESOLVED) suffix', () => {
+    const content = `# Research
+
+## Open Questions (RESOLVED)
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache TTL** — RESOLVED: 5 minutes`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes when Open Questions section is empty', () => {
+    const content = `# Research
+
+## Open Questions
+
+## Next Steps
+Proceed to planning.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes when all individual questions are marked RESOLVED', () => {
+    const content = `# Research
+
+## Open Questions
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache strategy** — RESOLVED: Use Redis with 5min TTL`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+    expect(result.unresolvedQuestions).toEqual([]);
+  });
+
+  it('passes with empty research content', () => {
+    const result = checkResearchGate('');
+    expect(result.pass).toBe(true);
+  });
+
+  // ── Fail cases ──────────────────────────────────────────────────────────
+
+  it('fails when Open Questions section has unresolved numbered items', () => {
+    const content = `# Research
+
+## Open Questions
+
+1. **Hash prefix** — keep or change?
+2. **Cache TTL** — what duration?
+
+## Recommendations
+Use TypeScript.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(2);
+    expect(result.unresolvedQuestions[0]).toContain('Hash prefix');
+    expect(result.unresolvedQuestions[1]).toContain('Cache TTL');
+  });
+
+  it('fails when Open Questions has bullet-point items', () => {
+    const content = `# Research
+
+## Open Questions
+
+- **Auth strategy** — OAuth vs API keys?
+- **Database** — Postgres or SQLite?`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(2);
+  });
+
+  it('fails with mix of resolved and unresolved questions', () => {
+    const content = `# Research
+
+## Open Questions
+
+1. **Hash prefix** — RESOLVED: Use "guest_contract:"
+2. **Cache TTL** — what duration?
+3. **Auth flow** — RESOLVED: OAuth2
+4. **Rate limiting** — needs decision`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(2);
+    expect(result.unresolvedQuestions[0]).toContain('Cache TTL');
+    expect(result.unresolvedQuestions[1]).toContain('Rate limiting');
+  });
+
+  it('fails with prose-style open questions (no list formatting)', () => {
+    const content = `# Research
+
+## Open Questions
+
+We still need to determine the hashing strategy and whether
+the cache should be shared across instances.
+
+## Recommendations
+Use TypeScript.`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(1);
+    expect(result.unresolvedQuestions[0]).toContain('unstructured');
+  });
+
+  it('fails when Open Questions is the last section (no next heading)', () => {
+    const content = `# Research
+
+## Key Findings
+Good stuff.
+
+## Open Questions
+
+1. **Deployment strategy** — containers vs serverless?`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(1);
+    expect(result.unresolvedQuestions[0]).toContain('Deployment strategy');
+  });
+
+  // ── Edge cases ──────────────────────────────────────────────────────────
+
+  it('handles case-insensitive heading match', () => {
+    const content = `# Research
+
+## open questions
+
+1. **Something** — unclear`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+  });
+
+  it('does not match subsection headings (### Open Questions)', () => {
+    // Only ## level headings should trigger the gate
+    const content = `# Research
+
+## Findings
+
+### Open Questions
+These are just notes, not blocking.
+
+1. **Minor thing** — just a thought`;
+
+    // ### level = subsection under Findings, not the formal gate section
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(true);
+  });
+
+  it('handles asterisk-style bullet points', () => {
+    const content = `# Research
+
+## Open Questions
+
+* **Strategy A** — needs evaluation
+* **Strategy B** — RESOLVED: go with B`;
+
+    const result = checkResearchGate(content);
+    expect(result.pass).toBe(false);
+    expect(result.unresolvedQuestions).toHaveLength(1);
+    expect(result.unresolvedQuestions[0]).toContain('Strategy A');
+  });
+});

package/sdk/src/research-gate.ts

@@ -0,0 +1,94 @@
+/**
+ * Research gate — validates RESEARCH.md for unresolved open questions
+ * before allowing plan-phase to proceed (#1602).
+ *
+ * Pure functions: no I/O, no side effects. The caller reads the file
+ * and passes the content string.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ResearchGateResult {
+  /** Whether research is clear to proceed to planning */
+  pass: boolean;
+  /** Unresolved questions found (empty if pass=true) */
+  unresolvedQuestions: string[];
+}
+
+// ─── Open questions detection ───────────────────────────────────────────────
+
+/**
+ * Check RESEARCH.md content for unresolved open questions.
+ *
+ * Rules:
+ * - If no "## Open Questions" section exists → pass
+ * - If section header has "(RESOLVED)" suffix → pass
+ * - If section exists but is empty (only whitespace before next heading) → pass
+ * - Otherwise → fail with list of unresolved questions
+ */
+export function checkResearchGate(researchContent: string): ResearchGateResult {
+  // Find "## Open Questions" section (case-insensitive)
+  const sectionMatch = researchContent.match(
+    /^##\s+Open\s+Questions\b([^\n]*)/im,
+  );
+
+  if (!sectionMatch) {
+    return { pass: true, unresolvedQuestions: [] };
+  }
+
+  // Check for (RESOLVED) suffix on the heading
+  const headingSuffix = sectionMatch[1].trim();
+  if (/\(resolved\)/i.test(headingSuffix)) {
+    return { pass: true, unresolvedQuestions: [] };
+  }
+
+  // Extract section content until next heading or EOF
+  const headingIndex = researchContent.indexOf(sectionMatch[0]);
+  const afterHeading = researchContent.slice(headingIndex + sectionMatch[0].length);
+
+  // Find next heading at same or higher level
+  const nextHeadingMatch = afterHeading.match(/\n##\s+[^\n]/);
+  const sectionBody = nextHeadingMatch
+    ? afterHeading.slice(0, nextHeadingMatch.index)
+    : afterHeading;
+
+  // Extract question items (numbered list or bullet points)
+  const unresolvedQuestions: string[] = [];
+  let totalQuestionLines = 0;
+  const lines = sectionBody.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Match: "1. **Question**", "- **Question**", "* **Question**", "1. Question"
+    const questionMatch = trimmed.match(
+      /^(?:\d+[.)]\s*|\*\s+|-\s+)\*{0,2}([^*\n]+)\*{0,2}/,
+    );
+    if (questionMatch) {
+      totalQuestionLines++;
+      const questionText = questionMatch[1].trim();
+      // Skip questions marked as resolved inline (handles — RESOLVED, - RESOLVED, RESOLVED:, etc.)
+      if (!/\bresolved\b/i.test(trimmed)) {
+        unresolvedQuestions.push(questionText);
+      }
+    }
+  }
+
+  // Empty section body → pass
+  if (sectionBody.trim() === '') {
+    return { pass: true, unresolvedQuestions: [] };
+  }
+
+  // All question lines were resolved → pass
+  if (totalQuestionLines > 0 && unresolvedQuestions.length === 0) {
+    return { pass: true, unresolvedQuestions: [] };
+  }
+
+  // Unresolved questions found → fail
+  if (unresolvedQuestions.length > 0) {
+    return { pass: false, unresolvedQuestions };
+  }
+
+  // Section has content but no parseable question lines → fail conservatively
+  // (e.g., prose-style questions without list formatting)
+  return { pass: false, unresolvedQuestions: ['(unstructured open questions detected — review ## Open Questions section)'] };
+}

package/sdk/src/runtime-bridge-options.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { SDD } from './index.js';
+import { SDDEventType, type SDDEvent } from './types.js';
+
+describe('SDD runtime bridge options', () => {
+  it('strictSdk option is honored by createTools dispatch seam', async () => {
+    const sdd = new SDD({
+      projectDir: process.cwd(),
+      strictSdk: true,
+      allowFallbackToSubprocess: true,
+      sessionId: 'test-session',
+    });
+
+    const events: SDDEvent[] = [];
+    sdd.onEvent((event) => events.push(event));
+
+    await expect(sdd.createTools().exec('nonexistent-command', [])).rejects.toThrow(
+      "Strict SDK mode: command 'nonexistent-command' has no native adapter",
+    );
+
+    const streamEvent = events.find((event) => event.type === SDDEventType.StreamEvent);
+    expect(streamEvent).toBeDefined();
+    expect(streamEvent).toMatchObject({
+      type: SDDEventType.StreamEvent,
+      sessionId: 'test-session',
+      event: {
+        type: 'query_dispatch',
+        command: 'nonexistent-command',
+        outcome: 'error',
+      },
+    });
+  });
+});

package/sdk/src/runtime-gate.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Unit tests for runtime-gate.ts
+ *
+ * Regression tests for #2832: sdd-sdk auto silently routed Codex (and other
+ * non-Claude) runtime projects through the Claude Agent SDK, picked
+ * Claude-Sonnet defaults from the profile map, and reported instant failures.
+ * The gate fails fast with an actionable error so users either set the right
+ * runtime or fall back to the in-session SDD slash commands.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { assertRuntimeSupportsAutoMode } from './runtime-gate.js';
+
+describe('assertRuntimeSupportsAutoMode', () => {
+  let prevEnv: string | undefined;
+  beforeEach(() => {
+    prevEnv = process.env.SDD_RUNTIME;
+    delete process.env.SDD_RUNTIME;
+  });
+  afterEach(() => {
+    if (prevEnv === undefined) delete process.env.SDD_RUNTIME;
+    else process.env.SDD_RUNTIME = prevEnv;
+  });
+
+  it('passes for runtime: claude (config)', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'claude' })).not.toThrow();
+  });
+
+  it('passes when no runtime configured (defaults to claude)', () => {
+    expect(() => assertRuntimeSupportsAutoMode(undefined)).not.toThrow();
+    expect(() => assertRuntimeSupportsAutoMode({})).not.toThrow();
+  });
+
+  it('throws for runtime: codex via config', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'codex' })).toThrow(/codex/);
+  });
+
+  it('throws for SDD_RUNTIME=codex even when config says claude', () => {
+    process.env.SDD_RUNTIME = 'codex';
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'claude' })).toThrow(/codex/);
+  });
+
+  it('error message references issue #2832 and slash-command workaround', () => {
+    let caught: Error | undefined;
+    try {
+      assertRuntimeSupportsAutoMode({ runtime: 'codex' });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeDefined();
+    expect(caught!.message).toMatch(/#2832/);
+    expect(caught!.message).toMatch(/sdd-discuss-phase|sdd-plan-phase|sdd-execute-phase/);
+  });
+
+  it('throws for gemini runtime', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'gemini' })).toThrow();
+  });
+
+  it('throws for opencode runtime', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'opencode' })).toThrow();
+  });
+
+  it('passes for unknown runtime values (fall through to claude default)', () => {
+    // Mirrors detectRuntime: unknown values are NOT in SUPPORTED_RUNTIMES,
+    // so they fall through to 'claude' rather than hard-blocking.
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'totally-bogus' })).not.toThrow();
+  });
+
+  it('attributes source to config when SDD_RUNTIME is set to an unsupported value', () => {
+    // Unsupported env values fall through to config in detectRuntime; the
+    // gate's error message must report config (not the discarded env value)
+    // as the source so users debug the right thing.
+    process.env.SDD_RUNTIME = 'unsupported-env';
+    let caught: Error | undefined;
+    try {
+      assertRuntimeSupportsAutoMode({ runtime: 'codex' });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeDefined();
+    expect(caught!.message).toMatch(/config\.runtime="codex"/);
+    expect(caught!.message).not.toMatch(/SDD_RUNTIME=unsupported-env/);
+  });
+});

package/sdk/src/runtime-gate.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime gate — guards entry points that only support the Claude runtime.
+ *
+ * The autonomous SDK orchestrator (`sdd-sdk auto`) currently drives plan
+ * execution through `@anthropic-ai/claude-agent-sdk`. It has no Codex /
+ * Gemini / OpenCode dispatcher today, so silently routing a non-Claude
+ * project's autonomous run through the Claude path is incorrect: it picks
+ * Claude models, hits Claude APIs, and confuses users debugging "why is my
+ * Codex run choosing claude-sonnet-4-6?" (issue #2832).
+ *
+ * Fail fast with an actionable error instead. The fix surfaces the limitation
+ * up front and points users at the supported in-session SDD slash commands
+ * for non-Claude runtimes.
+ */
+import { detectRuntime, SUPPORTED_RUNTIMES, type Runtime } from './query/helpers.js';
+
+/**
+ * Throw a clear error when the active runtime is not Claude.
+ *
+ * Precedence mirrors `detectRuntime`: `SDD_RUNTIME` env var > `config.runtime`
+ * > `'claude'`. Unknown / missing runtime values default to Claude (the
+ * historical behavior) so existing Claude users are unaffected.
+ *
+ * @param config Project config (with optional `runtime` field).
+ * @throws Error with a runtime-specific actionable message when non-Claude.
+ */
+export function assertRuntimeSupportsAutoMode(config?: Record<string, unknown> | { runtime?: unknown }): void {
+  const cfg = (config ?? {}) as Record<string, unknown>;
+  const runtime: Runtime = detectRuntime({ runtime: cfg.runtime });
+  if (runtime === 'claude') return;
+
+  // Source attribution must reflect what `detectRuntime()` actually used:
+  // a `SDD_RUNTIME` value that isn't in SUPPORTED_RUNTIMES falls through to
+  // the config tier, so reporting it as the source would be misleading.
+  const env = process.env.SDD_RUNTIME;
+  const envIsSupported =
+    typeof env === 'string' && (SUPPORTED_RUNTIMES as readonly string[]).includes(env);
+  const source = envIsSupported
+    ? `SDD_RUNTIME=${env}`
+    : `config.runtime="${String(cfg.runtime ?? '')}"`;
+
+  throw new Error(
+    `sdd-sdk auto currently supports the Claude runtime only ` +
+    `(detected runtime=${runtime} via ${source}). ` +
+    `Autonomous terminal runs through the Claude Agent SDK; non-Claude ` +
+    `runtimes (Codex, Gemini, OpenCode, etc.) must drive SDD via the ` +
+    `in-session slash commands (e.g. /sdd-discuss-phase, /sdd-plan-phase, ` +
+    `/sdd-execute-phase) until issue #2832 lands a multi-runtime executor. ` +
+    `To run on Claude anyway, unset SDD_RUNTIME and set runtime: "claude" ` +
+    `in .planning/config.json.`,
+  );
+}

package/sdk/src/sdd-tools-error.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { SDDToolsError } from './sdd-tools-error.js';
+
+describe('SDDToolsError constructors', () => {
+  it('builds timeout-classified errors', () => {
+    const err = SDDToolsError.timeout('timeout', 'state', ['load'], '', 1000);
+    expect(err.classification).toEqual({ kind: 'timeout', timeoutMs: 1000 });
+    expect(err.exitCode).toBeNull();
+  });
+
+  it('builds failure-classified errors', () => {
+    const err = SDDToolsError.failure('boom', 'state', ['load'], 1);
+    expect(err.classification).toEqual({ kind: 'failure' });
+    expect(err.exitCode).toBe(1);
+  });
+
+  it('defaults direct constructor to failure classification', () => {
+    const err = new SDDToolsError('boom', 'state', ['load'], 1, 'stderr');
+    expect(err.classification).toEqual({ kind: 'failure' });
+  });
+});

package/sdk/src/sdd-tools-error.ts

@@ -0,0 +1,65 @@
+export interface SDDToolsErrorClassification {
+  kind: 'timeout' | 'failure';
+  timeoutMs?: number;
+}
+
+function timeoutClassification(timeoutMs?: number): SDDToolsErrorClassification {
+  return timeoutMs === undefined ? { kind: 'timeout' } : { kind: 'timeout', timeoutMs };
+}
+
+function failureClassification(): SDDToolsErrorClassification {
+  return { kind: 'failure' };
+}
+
+export class SDDToolsError extends Error {
+  constructor(
+    message: string,
+    public readonly command: string,
+    public readonly args: string[],
+    public readonly exitCode: number | null,
+    public readonly stderr: string,
+    options?: { cause?: unknown; classification?: SDDToolsErrorClassification },
+  ) {
+    super(message, options);
+    this.name = 'SDDToolsError';
+    this.classification = options?.classification ?? failureClassification();
+  }
+
+  static timeout(
+    message: string,
+    command: string,
+    args: string[],
+    stderr = '',
+    timeoutMs?: number,
+    options?: { cause?: unknown; exitCode?: number | null },
+  ): SDDToolsError {
+    return new SDDToolsError(
+      message,
+      command,
+      args,
+      options?.exitCode ?? null,
+      stderr,
+      { cause: options?.cause, classification: timeoutClassification(timeoutMs) },
+    );
+  }
+
+  static failure(
+    message: string,
+    command: string,
+    args: string[],
+    exitCode: number | null,
+    stderr = '',
+    options?: { cause?: unknown },
+  ): SDDToolsError {
+    return new SDDToolsError(
+      message,
+      command,
+      args,
+      exitCode,
+      stderr,
+      { cause: options?.cause, classification: failureClassification() },
+    );
+  }
+
+  public readonly classification: SDDToolsErrorClassification;
+}