@opengsd/get-shit-done-redux 1.0.0

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 { GSD } from './index.js';
+import { GSDEventType, type GSDEvent } from './types.js';
+
+describe('GSD runtime bridge options', () => {
+  it('strictSdk option is honored by createTools dispatch seam', async () => {
+    const gsd = new GSD({
+      projectDir: process.cwd(),
+      strictSdk: true,
+      allowFallbackToSubprocess: true,
+      sessionId: 'test-session',
+    });
+
+    const events: GSDEvent[] = [];
+    gsd.onEvent((event) => events.push(event));
+
+    await expect(gsd.createTools().exec('nonexistent-command', [])).rejects.toThrow(
+      "Strict SDK mode: command 'nonexistent-command' has no native adapter",
+    );
+
+    const streamEvent = events.find((event) => event.type === GSDEventType.StreamEvent);
+    expect(streamEvent).toBeDefined();
+    expect(streamEvent).toMatchObject({
+      type: GSDEventType.StreamEvent,
+      sessionId: 'test-session',
+      event: {
+        type: 'query_dispatch',
+        command: 'nonexistent-command',
+        outcome: 'error',
+      },
+    });
+  });
+});

package/sdk/src/runtime-bridge-sync/index.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Pinning tests for the executeForCjs synchronous primitive.
+ *
+ * Covers:
+ * - Success path: known read-only command returns { ok: true, data, exitCode: 0 }
+ * - unknown_command: unknown command key returns { ok: false, errorKind: 'unknown_command' }
+ * - native_failure: handler that throws a generic Error returns { ok: false, errorKind: 'native_failure' }
+ * - internal_error mapping tracked as a TODO until a deterministic TypeError fixture exists
+ * - Idempotency: calling twice with identical input produces identical output
+ * - Sync nature: returned value is not a Promise
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import type { RuntimeBridgeSyncResult } from './index.js';
+
+// We import after build — the test runner loads the TS via tsx/vitest,
+// but executeForCjs creates a Worker which loads the compiled worker.js.
+// So we must build before running these tests. In CI, build runs first.
+// In local dev, run `npm run build` before vitest.
+
+let executeForCjs: (input: import('./index.js').ExecuteForCjsInput) => RuntimeBridgeSyncResult;
+
+beforeAll(async () => {
+  // Dynamic import so we get an actionable error if the module is missing
+  // (RED phase: will fail here with "Cannot find module")
+  const mod = await import('./index.js');
+  executeForCjs = mod.executeForCjs;
+});
+
+describe('executeForCjs - sync primitive', () => {
+  it('returns a non-Promise object synchronously', () => {
+    const result = executeForCjs({
+      registryCommand: 'generate-slug',
+      registryArgs: ['My Phase'],
+      legacyCommand: 'generate-slug',
+      legacyArgs: ['My Phase'],
+      mode: 'json',
+      projectDir: '/tmp',
+    });
+
+    // Must NOT be a Promise
+    expect(result).not.toBeInstanceOf(Promise);
+    expect(typeof result).toBe('object');
+    // .ok must be accessible synchronously
+    expect('ok' in result).toBe(true);
+  });
+
+  it('success: generate-slug returns ok:true with data and exitCode:0', () => {
+    const result = executeForCjs({
+      registryCommand: 'generate-slug',
+      registryArgs: ['My Phase'],
+      legacyCommand: 'generate-slug',
+      legacyArgs: ['My Phase'],
+      mode: 'json',
+      projectDir: '/tmp',
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('Expected ok:true');
+    expect(result.exitCode).toBe(0);
+    expect(result.data).toBeDefined();
+    // generate-slug returns { slug: 'my-phase' }
+    expect((result.data as Record<string, unknown>).slug).toBe('my-phase');
+  });
+
+  it('unknown_command: returns ok:false with errorKind unknown_command', () => {
+    const result = executeForCjs({
+      registryCommand: '__nonexistent_command_xyz__',
+      registryArgs: [],
+      legacyCommand: '__nonexistent_command_xyz__',
+      legacyArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('Expected ok:false');
+    expect(result.errorKind).toBe('unknown_command');
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it('native_failure: handler execution failure is classified as native_failure', () => {
+    // generate-slug with no args throws a GSDError (validation) — that maps to validation_error.
+    // We need a command that throws a plain Error (GSDToolsError classification.kind='failure').
+    //
+    // Phase 5.1 fix note: the Phase 5.0 fixture used projectDir='/tmp' with an absolute
+    // path arg that started with /tmp — after the worker fix threads projectDir correctly,
+    // frontmatter.get returns a soft ok:true error instead of throwing (path escape check
+    // passes, then realpath on the nonexistent path returns ok:true with error field).
+    // Updated fixture: use a completely nonexistent projectDir so resolvePathUnderProject
+    // calls realpath('/nonexistent...') and throws ENOENT, which is classified as native_failure.
+    const result = executeForCjs({
+      registryCommand: 'frontmatter.get',
+      registryArgs: ['file.md'],
+      legacyCommand: 'frontmatter get',
+      legacyArgs: ['file.md'],
+      mode: 'json',
+      projectDir: '/nonexistent-absolutely-does-not-exist-project-dir',
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('Expected ok:false');
+    expect(result.errorKind).toBe('native_failure');
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it.todo('internal_error: requires fixture command that throws TypeError');
+
+  it('unknown_command: unregistered command is classified as unknown_command', () => {
+    const result = executeForCjs({
+      registryCommand: '__nonexistent_xyz__',
+      registryArgs: [],
+      legacyCommand: '__nonexistent_xyz__',
+      legacyArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('Expected ok:false');
+    expect(result.errorKind).toBe('unknown_command');
+  });
+
+  it('idempotency: calling twice with identical input returns identical output', () => {
+    const input = {
+      registryCommand: 'generate-slug',
+      registryArgs: ['Idempotency Test'],
+      legacyCommand: 'generate-slug',
+      legacyArgs: ['Idempotency Test'],
+      mode: 'json' as const,
+      projectDir: '/tmp',
+    };
+
+    const result1 = executeForCjs(input);
+    const result2 = executeForCjs(input);
+
+    expect(result1.ok).toBe(result2.ok);
+    expect(result1.exitCode).toBe(result2.exitCode);
+    if (result1.ok && result2.ok) {
+      expect(JSON.stringify(result1.data)).toBe(JSON.stringify(result2.data));
+    }
+  });
+
+  it('idempotency: unknown command returns same errorKind on repeat calls', () => {
+    const input = {
+      registryCommand: '__idempotency_test_unknown__',
+      registryArgs: [],
+      legacyCommand: '__idempotency_test_unknown__',
+      legacyArgs: [],
+      mode: 'json' as const,
+      projectDir: '/tmp',
+    };
+
+    const result1 = executeForCjs(input);
+    const result2 = executeForCjs(input);
+
+    expect(result1.ok).toBe(false);
+    expect(result2.ok).toBe(false);
+    if (!result1.ok && !result2.ok) {
+      expect(result1.errorKind).toBe(result2.errorKind);
+      expect(result1.exitCode).toBe(result2.exitCode);
+    }
+  });
+});

package/sdk/src/runtime-bridge-sync/index.ts

@@ -0,0 +1,154 @@
+/**
+ * executeForCjs — synchronous SDK runtime bridge primitive.
+ *
+ * Provides a synchronous `executeForCjs()` function that CJS callers can use
+ * to invoke any registered SDK command without dealing with async/await or
+ * top-level-await restrictions that prevent CJS from using the async bridge.
+ *
+ * ## Mechanism
+ *
+ * Uses `synckit` (Atomics.wait + SharedArrayBuffer + worker_threads) to run
+ * the async `QueryRuntimeBridge.execute()` in a worker thread and block the
+ * calling thread until the result is available. The worker is spawned lazily
+ * on first call and reused for all subsequent calls.
+ *
+ * ## Worker overhead
+ *
+ * - First call (worker startup + native bridge construction): ~80 ms.
+ * - Subsequent calls (steady state): ~0.1 ms per call (excluding handler work).
+ *
+ * ## CRITICAL: Do NOT call from an async context
+ *
+ * `executeForCjs` uses `Atomics.wait` under the hood, which **blocks the
+ * calling thread**. Calling it from inside an async function that is itself
+ * running on the Node.js main thread event loop will **deadlock** because
+ * the event loop cannot process the worker's response message while blocked.
+ *
+ * Safe callers:
+ * - CJS modules evaluated at require-time (synchronous module initialisation).
+ * - Worker threads that are not using the event loop.
+ *
+ * Unsafe callers:
+ * - Any `async function` on the main thread.
+ * - Anything inside a `Promise` callback on the main thread.
+ *
+ * ## CJS consumption
+ *
+ * ```js
+ * const { executeForCjs } = require('@opengsd/gsd-sdk/dist/runtime-bridge-sync/index.js');
+ * const result = executeForCjs({ registryCommand: 'generate-slug', registryArgs: ['My Phase'], ... });
+ * if (result.ok) console.log(result.data); // { slug: 'my-phase' }
+ * ```
+ *
+ * @module runtime-bridge-sync
+ */
+
+import { createSyncFn } from 'synckit';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import type { RuntimeBridgeExecuteInput } from '../query-runtime-bridge.js';
+
+// Re-export the input type so callers can import it alongside executeForCjs
+export type { RuntimeBridgeExecuteInput };
+
+// Convenience alias for callers who prefer a shorter name
+export type ExecuteForCjsInput = RuntimeBridgeExecuteInput;
+
+// ─── Result type ─────────────────────────────────────────────────────────────
+
+/**
+ * The 6 canonical error kinds from ADR-0001 Dispatch Policy Module.
+ */
+export type SyncErrorKind =
+  | 'unknown_command'
+  | 'native_failure'
+  | 'native_timeout'
+  | 'fallback_failure'
+  | 'validation_error'
+  | 'internal_error';
+
+/**
+ * Discriminated union returned by `executeForCjs`.
+ *
+ * - `ok: true` — command executed successfully. `data` is the handler's return value.
+ * - `ok: false` — command failed. `errorKind` identifies the failure category.
+ */
+export type RuntimeBridgeSyncResult =
+  | { ok: true; data: unknown; exitCode: 0 }
+  | {
+      ok: false;
+      exitCode: number;
+      errorKind: SyncErrorKind;
+      errorDetails?: unknown;
+      stderrLines: string[];
+    };
+
+// ─── Lazy sync-fn factory ──────────────────────────────────────────────────
+
+// Resolve worker path to the compiled dist artifact.
+//
+// The worker MUST be the compiled JS file (dist/runtime-bridge-sync/worker.js),
+// NOT the TypeScript source. This is because:
+// 1. synckit spawns the worker via Node.js directly (no tsx transform).
+// 2. When vitest runs tests from the TS source tree, import.meta.url points to
+//    src/, not dist/. We must redirect to dist/ in all cases.
+//
+// Strategy: navigate from the current file's directory to the package root,
+// then resolve to dist/runtime-bridge-sync/worker.js.
+// The current file lives either in:
+//   src/runtime-bridge-sync/ (vitest TS source context)
+//   dist/runtime-bridge-sync/ (compiled CJS/ESM consumer context)
+// In both cases, two levels up is the package root (sdk/).
+const _moduleUrl = import.meta.url;
+
+function resolveWorkerPath(): string {
+  const currentDir = dirname(fileURLToPath(_moduleUrl));
+  // currentDir is either src/runtime-bridge-sync or dist/runtime-bridge-sync.
+  // Two levels up is the sdk/ package root.
+  const pkgRoot = join(currentDir, '..', '..');
+  return join(pkgRoot, 'dist', 'runtime-bridge-sync', 'worker.js');
+}
+
+let _syncFn: ((input: RuntimeBridgeExecuteInput) => RuntimeBridgeSyncResult) | null = null;
+
+function getSyncFn(): (input: RuntimeBridgeExecuteInput) => RuntimeBridgeSyncResult {
+  if (_syncFn) return _syncFn;
+  const workerPath = resolveWorkerPath();
+  _syncFn = createSyncFn<(input: RuntimeBridgeExecuteInput) => Promise<RuntimeBridgeSyncResult>>(
+    workerPath,
+    { timeout: 60_000 },
+  );
+  return _syncFn;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Execute a registered SDK command synchronously.
+ *
+ * This function blocks the calling thread until the command completes.
+ * It must NOT be called from an async context on the main event-loop thread
+ * (see module-level JSDoc for details).
+ *
+ * @param input - The command input, matching RuntimeBridgeExecuteInput.
+ * @returns A RuntimeBridgeSyncResult — either ok:true with data, or ok:false with errorKind.
+ *
+ * @example
+ * ```js
+ * const { executeForCjs } = require('@opengsd/gsd-sdk/dist/runtime-bridge-sync/index.js');
+ * const result = executeForCjs({
+ *   registryCommand: 'generate-slug',
+ *   registryArgs: ['My Phase'],
+ *   legacyCommand: 'generate-slug',
+ *   legacyArgs: ['My Phase'],
+ *   mode: 'json',
+ *   projectDir: '/path/to/project',
+ * });
+ * if (result.ok) {
+ *   console.log(result.data.slug); // 'my-phase'
+ * }
+ * ```
+ */
+export function executeForCjs(input: RuntimeBridgeExecuteInput): RuntimeBridgeSyncResult {
+  return getSyncFn()(input);
+}