gswd 0.1.0

package/lib/config.ts

@@ -0,0 +1,164 @@
+/**
+ * GSWD Config Module — config.json merge under gswd key
+ *
+ * Config is stored in .planning/config.json under the `gswd` key.
+ * Merge operations NEVER touch keys outside `gswd`.
+ *
+ * Schema: GSWD_SPEC.md Section 5.2
+ */
+
+import * as fs from 'node:fs';
+import { safeWriteJson } from './state.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface GswdAutoConfig {
+  policy: 'strict' | 'balanced' | 'aggressive';
+  allow_paid_integrations_under_budget: boolean;
+  default_auth_model: string;
+  default_data_store: string;
+  default_stack: string;
+  preapproved_integrations: string[];
+}
+
+export interface GswdConfig {
+  mode: string;
+  strict_gates: boolean;
+  max_parallel_agents: number;
+  external_research: boolean;
+  integration_budget_usd_month: number;
+  doc_verbosity: string;
+  phase_style: string;
+  auto: GswdAutoConfig;
+  [key: string]: unknown;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+/**
+ * Default GSWD config matching GSWD_SPEC Section 5.2.
+ */
+export const GSWD_CONFIG_DEFAULTS: GswdConfig = {
+  mode: 'balanced',
+  strict_gates: true,
+  max_parallel_agents: 4,
+  external_research: true,
+  integration_budget_usd_month: 100,
+  doc_verbosity: 'normal',
+  phase_style: 'thin',
+  auto: {
+    policy: 'balanced',
+    allow_paid_integrations_under_budget: false,
+    default_auth_model: 'passwordless_email',
+    default_data_store: 'sqlite',
+    default_stack: 'node_typescript',
+    preapproved_integrations: [],
+  },
+};
+
+// ─── Config CRUD ─────────────────────────────────────────────────────────────
+
+/**
+ * Read config.json. Returns empty object if missing or invalid.
+ */
+export function readConfig(configPath: string): Record<string, unknown> {
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Deep merge helper: merge source into target, source values take precedence.
+ * Only merges plain objects recursively; arrays and primitives are replaced.
+ */
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = result[key];
+
+    if (
+      typeof sourceVal === 'object' &&
+      sourceVal !== null &&
+      !Array.isArray(sourceVal) &&
+      typeof targetVal === 'object' &&
+      targetVal !== null &&
+      !Array.isArray(targetVal)
+    ) {
+      result[key] = deepMerge(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>
+      );
+    } else {
+      result[key] = sourceVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merge GSWD config into config.json under the `gswd` key.
+ * - Reads existing config (preserves ALL non-gswd keys)
+ * - Deep merges: existing gswd values take precedence over defaults
+ * - Fills in missing defaults
+ * - Writes back atomically
+ *
+ * CRITICAL: Never touches any key outside `gswd`.
+ */
+export function mergeGswdConfig(
+  configPath: string,
+  gswdOverrides?: Partial<GswdConfig>
+): void {
+  // Read existing config (preserves GSD keys, etc.)
+  const existing = readConfig(configPath);
+
+  // Start with defaults
+  let mergedGswd: Record<string, unknown> = { ...GSWD_CONFIG_DEFAULTS } as Record<string, unknown>;
+
+  // Apply overrides on top of defaults
+  if (gswdOverrides) {
+    mergedGswd = deepMerge(mergedGswd, gswdOverrides as Record<string, unknown>);
+  }
+
+  // Apply existing user values on top (user values take precedence)
+  const existingGswd = existing.gswd;
+  if (typeof existingGswd === 'object' && existingGswd !== null && !Array.isArray(existingGswd)) {
+    mergedGswd = deepMerge(mergedGswd, existingGswd as Record<string, unknown>);
+  }
+
+  // Write back: existing config with updated gswd key
+  existing.gswd = mergedGswd;
+  safeWriteJson(configPath, existing);
+}
+
+/**
+ * Get GSWD config with all defaults filled in for missing fields.
+ */
+export function getGswdConfig(configPath: string): GswdConfig {
+  const config = readConfig(configPath);
+  const gswdRaw = config.gswd;
+
+  if (typeof gswdRaw !== 'object' || gswdRaw === null || Array.isArray(gswdRaw)) {
+    return { ...GSWD_CONFIG_DEFAULTS };
+  }
+
+  // Merge defaults under existing values
+  const merged = deepMerge(
+    { ...GSWD_CONFIG_DEFAULTS } as Record<string, unknown>,
+    gswdRaw as Record<string, unknown>
+  );
+
+  return merged as GswdConfig;
+}

package/lib/imagine-agents.ts

@@ -0,0 +1,154 @@
+/**
+ * GSWD Imagine Agents Module — Agent definitions, orchestration, and result collection
+ *
+ * Provides batched parallel agent spawning that respects max_parallel_agents config.
+ * Agent definitions describe the 5 research agents from GSWD_SPEC Section 11.1.
+ * Actual Task() integration happens in the workflow orchestrator (imagine.ts).
+ *
+ * Schema: GSWD_SPEC.md Section 8.2 Steps 3-4, Section 11.1
+ */
+
+import * as fs from 'node:fs';
+import type { StarterBrief } from './imagine-input.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface AgentDefinition {
+  name: string;           // e.g., 'market-researcher'
+  definitionPath: string; // e.g., 'agents/gswd/market-researcher.md'
+  outputArtifact: string; // e.g., 'COMPETITION.md' (which artifact this feeds)
+  requiredHeadings: string[]; // Minimum output validation
+}
+
+export interface AgentResult {
+  agent: string;          // Agent name
+  content: string;        // Agent's output content
+  status: 'complete' | 'failed';
+  error?: string;         // Error message if failed
+  duration_ms?: number;   // Execution time
+}
+
+export type SpawnFn = (prompt: string) => Promise<string>;
+
+// ─── Agent Definitions ───────────────────────────────────────────────────────
+
+/**
+ * The 5 research agents for the Imagine stage.
+ * Names match GSWD_SPEC Section 11.1 file names.
+ */
+export const IMAGINE_AGENTS: AgentDefinition[] = [
+  {
+    name: 'market-researcher',
+    definitionPath: 'agents/gswd/market-researcher.md',
+    outputArtifact: 'COMPETITION.md',
+    requiredHeadings: ['## Market Overview', '## Competitors'],
+  },
+  {
+    name: 'icp-persona',
+    definitionPath: 'agents/gswd/icp-persona.md',
+    outputArtifact: 'ICP.md',
+    requiredHeadings: ['## ICP Profile', '## Pain Points'],
+  },
+  {
+    name: 'positioning',
+    definitionPath: 'agents/gswd/positioning.md',
+    outputArtifact: 'GTM.md',
+    requiredHeadings: ['## Value Proposition'],
+  },
+  {
+    name: 'brainstorm-alternatives',
+    definitionPath: 'agents/gswd/brainstorm-alternatives.md',
+    outputArtifact: 'DIRECTIONS',
+    requiredHeadings: ['## Direction 1', '## Direction 2', '## Direction 3'],
+  },
+  {
+    name: 'devils-advocate',
+    definitionPath: 'agents/gswd/devils-advocate.md',
+    outputArtifact: 'RISKS',
+    requiredHeadings: ['## Risks'],
+  },
+];
+
+// ─── Prompt Building ─────────────────────────────────────────────────────────
+
+/**
+ * Build the prompt that will be passed to Task() for an agent.
+ *
+ * Reads agent definition file and injects StarterBrief as context.
+ */
+export function buildAgentPrompt(agent: AgentDefinition, brief: StarterBrief): string {
+  let definition: string;
+  try {
+    definition = fs.readFileSync(agent.definitionPath, 'utf-8');
+  } catch {
+    definition = `Agent: ${agent.name}\nRole: Research agent for ${agent.outputArtifact}`;
+  }
+
+  const briefJson = JSON.stringify(brief, null, 2);
+
+  return `${definition}
+
+<starter_brief>
+${briefJson}
+</starter_brief>
+
+Produce your output now. Include all required headings: ${agent.requiredHeadings.join(', ')}.`;
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────
+
+/**
+ * Orchestrate agents in batches respecting maxParallel concurrency limit.
+ *
+ * Splits agents into batches of maxParallel size, executes each batch
+ * concurrently, collects results. Failed agents are marked with status: 'failed'
+ * but do not crash the orchestration.
+ *
+ * @param agents - Array of agent definitions to spawn
+ * @param maxParallel - Maximum concurrent agents (from config.max_parallel_agents)
+ * @param brief - StarterBrief input for all agents
+ * @param spawnFn - Function that spawns an agent (Task() wrapper)
+ * @returns All agent results including failures
+ */
+export async function orchestrateAgents(
+  agents: AgentDefinition[],
+  maxParallel: number,
+  brief: StarterBrief,
+  spawnFn: SpawnFn,
+): Promise<AgentResult[]> {
+  const results: AgentResult[] = [];
+
+  // Split into batches
+  for (let i = 0; i < agents.length; i += maxParallel) {
+    const batch = agents.slice(i, i + maxParallel);
+
+    // Execute batch in parallel
+    const batchPromises = batch.map(async (agent): Promise<AgentResult> => {
+      const start = Date.now();
+      try {
+        const prompt = buildAgentPrompt(agent, brief);
+        const content = await spawnFn(prompt);
+        return {
+          agent: agent.name,
+          content,
+          status: 'complete',
+          duration_ms: Date.now() - start,
+        };
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          agent: agent.name,
+          content: '',
+          status: 'failed',
+          error: message,
+          duration_ms: Date.now() - start,
+        };
+      }
+    });
+
+    const batchResults = await Promise.all(batchPromises);
+    results.push(...batchResults);
+  }
+
+  return results;
+}

package/lib/imagine-gate.ts

@@ -0,0 +1,156 @@
+/**
+ * GSWD Imagine Gate Module — Decision gate validation for DECISIONS.md
+ *
+ * Pure function: validates DECISIONS.md against hard gate requirements.
+ * No side effects, no file writes, no state mutations.
+ *
+ * Gate requirements (GSWD_SPEC Section 3.3, Appendix A1):
+ * - ## Frozen Decisions: >= 8 items
+ * - ## Success Metrics: 1-3 items
+ * - ## Out of Scope: >= 1 item
+ * - ## Risks & Mitigations: >= 5 items
+ * - ## Open Questions: >= 0 items (section must exist)
+ */
+
+import { validateHeadings, extractHeadingContent } from './parse.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface InsufficientCount {
+  section: string;
+  required: number;
+  actual: number;
+  constraint?: string;  // e.g., "1-3" for metrics range
+}
+
+export interface GateResult {
+  passed: boolean;
+  missing_sections: string[];
+  insufficient_counts: InsufficientCount[];
+  summary: string;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Count list items in a section.
+ *
+ * Counts lines starting with:
+ * - `- ` (bullet)
+ * - `* ` (bullet)
+ * - `N. ` or `N) ` (numbered)
+ * - `### ` (sub-headings as items)
+ *
+ * Returns 0 for empty/null/undefined content.
+ */
+export function countListItems(content: string | null | undefined): number {
+  if (!content) return 0;
+
+  const lines = content.split('\n');
+  let count = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (/^[-*]\s+/.test(trimmed)) {
+      count++;
+    } else if (/^\d+[.)]\s+/.test(trimmed)) {
+      count++;
+    } else if (/^###\s+/.test(trimmed)) {
+      count++;
+    }
+  }
+
+  return count;
+}
+
+// ─── Gate Validation ─────────────────────────────────────────────────────────
+
+/**
+ * Validate DECISIONS.md against the hard gate requirements.
+ *
+ * Step 1: Required headings (via parse.ts validateHeadings)
+ * Step 2: Item counts per section (via parse.ts extractHeadingContent + countListItems)
+ * Step 3: Build structured result
+ *
+ * Returns: GateResult with passed/failed status, missing sections, and count issues.
+ */
+export function validateDecisionGate(decisionsContent: string): GateResult {
+  // Step 1: Required headings
+  const headingResult = validateHeadings(decisionsContent, 'DECISIONS.md');
+
+  // Step 2: Count items per section
+  const insufficient: InsufficientCount[] = [];
+
+  // Frozen Decisions: >= 8
+  const frozenSection = extractHeadingContent(decisionsContent, '## Frozen Decisions');
+  const frozenCount = countListItems(frozenSection);
+  if (frozenCount < 8) {
+    insufficient.push({
+      section: 'Frozen Decisions',
+      required: 8,
+      actual: frozenCount,
+    });
+  }
+
+  // Success Metrics: 1-3
+  const metricsSection = extractHeadingContent(decisionsContent, '## Success Metrics');
+  const metricsCount = countListItems(metricsSection);
+  if (metricsCount < 1 || metricsCount > 3) {
+    insufficient.push({
+      section: 'Success Metrics',
+      required: metricsCount < 1 ? 1 : 3,
+      actual: metricsCount,
+      constraint: '1-3',
+    });
+  }
+
+  // Out of Scope: >= 1
+  const outOfScopeSection = extractHeadingContent(decisionsContent, '## Out of Scope');
+  const outOfScopeCount = countListItems(outOfScopeSection);
+  if (outOfScopeCount < 1) {
+    insufficient.push({
+      section: 'Out of Scope',
+      required: 1,
+      actual: outOfScopeCount,
+    });
+  }
+
+  // Risks & Mitigations: >= 5
+  const risksSection = extractHeadingContent(decisionsContent, '## Risks & Mitigations');
+  const risksCount = countListItems(risksSection);
+  if (risksCount < 5) {
+    insufficient.push({
+      section: 'Risks & Mitigations',
+      required: 5,
+      actual: risksCount,
+    });
+  }
+
+  // Open Questions: >= 0 (section must exist, but can be empty)
+  // No count check needed — heading presence is sufficient
+
+  // Step 3: Build result
+  const passed = headingResult.valid && insufficient.length === 0;
+  const totalIssues = headingResult.missing.length + insufficient.length;
+
+  let summary: string;
+  if (passed) {
+    summary = 'PASS: All 5 sections present, counts valid';
+  } else {
+    const issues: string[] = [];
+    if (headingResult.missing.length > 0) {
+      issues.push(`${headingResult.missing.length} missing heading(s)`);
+    }
+    if (insufficient.length > 0) {
+      issues.push(`${insufficient.length} insufficient count(s)`);
+    }
+    summary = `FAIL: ${totalIssues} issue(s) — ${issues.join(', ')}`;
+  }
+
+  return {
+    passed,
+    missing_sections: headingResult.missing,
+    insufficient_counts: insufficient,
+    summary,
+  };
+}