sofia-cli 0.1.1

package/src/phases/phaseHandlers.ts

@@ -0,0 +1,450 @@
+/**
+ * Phase handler factory.
+ *
+ * Creates PhaseHandler instances for each workshop phase.
+ * Each handler:
+ *   - Builds the system prompt from canonical prompts
+ *   - Provides grounding document references
+ *   - Extracts structured data from LLM responses
+ */
+import type { PhaseHandler } from '../loop/conversationLoop.js';
+import type { LoopIO } from '../loop/conversationLoop.js';
+import type { PhaseValue, WorkshopSession } from '../shared/schemas/session.js';
+import { buildSystemPrompt, getPhaseReferences } from '../prompts/promptLoader.js';
+import {
+  extractBusinessContext,
+  extractWorkflow,
+  extractIdeas,
+  extractEvaluation,
+  extractSelection,
+  extractPlan,
+  extractPocState,
+  extractSessionName,
+} from './phaseExtractors.js';
+import { DiscoveryEnricher } from './discoveryEnricher.js';
+import type { WebSearchClient } from './discoveryEnricher.js';
+import type { McpManager } from '../mcp/mcpManager.js';
+import { buildSummarizedContext, renderSummarizedContext } from './contextSummarizer.js';
+
+// ── Initial message helper ──────────────────────────────────────────────────
+
+const PHASE_INTROS: Record<PhaseValue, string> = {
+  Discover:
+    'Introduce the Discover phase. Ask about the business, its challenges, and what area to focus on.',
+  Ideate:
+    'Introduce the Ideate phase. Review the business context and workflow, then brainstorm AI-powered ideas.',
+  Design:
+    'Introduce the Design phase. Review the generated ideas and help evaluate them using a feasibility-value matrix.',
+  Select:
+    'Introduce the Select phase. Present the top-ranked ideas and help the user choose the best one to implement.',
+  Plan: 'Introduce the Plan phase. Create an implementation plan with milestones for the selected idea.',
+  Develop:
+    'Introduce the Develop phase. Generate proof-of-concept code for the planned implementation.',
+  Complete: 'The workshop is complete. Summarize the results.',
+};
+
+const PHASE_RESUMES: Record<PhaseValue, string> = {
+  Discover:
+    'We are resuming the Discover phase. Summarize what was discussed so far and ask the next question.',
+  Ideate:
+    'We are resuming the Ideate phase. Summarize the ideas generated so far and continue brainstorming.',
+  Design:
+    'We are resuming the Design phase. Summarize the evaluation progress and continue with the next step.',
+  Select: 'We are resuming the Select phase. Summarize the selection process so far and continue.',
+  Plan: 'We are resuming the Plan phase. Summarize the plan progress and continue with the next milestone.',
+  Develop:
+    'We are resuming the Develop phase. Summarize the PoC development progress and continue.',
+  Complete: 'The workshop is complete. Summarize the results.',
+};
+
+/**
+ * Generate the initial message for a phase based on session state.
+ * New sessions get an introduction; resumed sessions get a progress summary prompt.
+ */
+function buildInitialMessage(phase: PhaseValue, session: WorkshopSession): string {
+  const phaseTurns = (session.turns ?? []).filter((t) => t.phase === phase);
+  if (phaseTurns.length > 0) {
+    return PHASE_RESUMES[phase];
+  }
+  return PHASE_INTROS[phase];
+}
+
+// ── Discover Phase ──────────────────────────────────────────────────────────
+
+export interface DiscoverHandlerConfig {
+  /** IO for permission prompts */
+  io?: LoopIO;
+  /** MCP manager for WorkIQ tool calls */
+  mcpManager?: McpManager;
+  /** Web search client */
+  webSearchClient?: WebSearchClient;
+}
+
+function createDiscoverHandler(config?: DiscoverHandlerConfig): PhaseHandler {
+  let cachedPrompt: string | null = null;
+  let cachedRefs: string[] | null = null;
+  let enrichmentDone = false;
+
+  return {
+    phase: 'Discover',
+
+    buildSystemPrompt(_session: WorkshopSession): string {
+      // Lazy-loaded in run() but we need sync return.
+      // The prompt is pre-loaded before the loop starts.
+      return (
+        cachedPrompt ??
+        'You are an AI Discovery Workshop facilitator helping with the Discover phase.'
+      );
+    },
+
+    getReferences(_session: WorkshopSession): string[] {
+      return cachedRefs ?? [];
+    },
+
+    extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession> {
+      const updates: Partial<WorkshopSession> = {};
+      const bc = extractBusinessContext(response);
+      if (bc) updates.businessContext = bc;
+      const wf = extractWorkflow(response);
+      if (wf) updates.workflow = wf;
+      // First-write-wins: only set name if session doesn't already have one
+      if (!session.name) {
+        const sessionName = extractSessionName(response);
+        if (sessionName) updates.name = sessionName;
+      }
+      return updates;
+    },
+
+    async postExtract(session: WorkshopSession): Promise<Partial<WorkshopSession>> {
+      // Trigger enrichment once when businessContext is first available
+      if (enrichmentDone || !session.businessContext) return {};
+      enrichmentDone = true;
+
+      const enricher = new DiscoveryEnricher();
+      const io = config?.io;
+      const mcpManager = config?.mcpManager;
+      const webSearchClient = config?.webSearchClient;
+
+      // Only run enrichment if at least one source is available
+      if (!webSearchClient && (!mcpManager || !mcpManager.isAvailable('workiq'))) {
+        return {};
+      }
+
+      const companySummary = session.businessContext.businessDescription;
+
+      try {
+        const enrichment = await enricher.enrich({
+          companySummary,
+          mcpManager:
+            mcpManager ??
+            ({ isAvailable: () => false, callTool: async () => ({}) } as unknown as McpManager),
+          io: io ?? {
+            write: () => {},
+            writeActivity: () => {},
+            writeToolSummary: () => {},
+            readInput: async () => null,
+            showDecisionGate: async () => ({ choice: 'continue' as const }),
+            isJsonMode: false,
+            isTTY: false,
+          },
+          webSearchClient,
+        });
+
+        return {
+          discovery: {
+            enrichment,
+          },
+        };
+      } catch {
+        // Enrichment failure is non-fatal
+        return {};
+      }
+    },
+
+    isComplete(session: WorkshopSession, _response: string): boolean {
+      // Discover is complete when we have business context and workflow
+      return !!(session.businessContext && session.workflow);
+    },
+
+    getInitialMessage(session: WorkshopSession): string {
+      return buildInitialMessage('Discover', session);
+    },
+
+    // Extension: allows pre-loading async prompts
+    async _preload() {
+      cachedPrompt = await buildSystemPrompt('Discover');
+      cachedRefs = await getPhaseReferences('Discover');
+    },
+  } as PhaseHandler & { _preload(): Promise<void> };
+}
+
+// ── Ideate Phase ────────────────────────────────────────────────────────────
+
+function createIdeateHandler(): PhaseHandler & { _preload(): Promise<void> } {
+  let cachedPrompt: string | null = null;
+  let cachedRefs: string[] | null = null;
+
+  return {
+    phase: 'Ideate',
+
+    buildSystemPrompt(session: WorkshopSession): string {
+      // FR-016: Use unified summarized context instead of ad-hoc injection
+      const context = renderSummarizedContext(buildSummarizedContext(session));
+      return (cachedPrompt ?? 'You are facilitating the Ideate phase.') + context;
+    },
+
+    getReferences(_session: WorkshopSession): string[] {
+      return cachedRefs ?? [];
+    },
+
+    extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession> {
+      const ideas = extractIdeas(response);
+      if (ideas && ideas.length > 0) {
+        // Merge with existing ideas (append, deduplicate by id)
+        const existing = session.ideas ?? [];
+        const existingIds = new Set(existing.map((i) => i.id));
+        const merged = [...existing, ...ideas.filter((i) => !existingIds.has(i.id))];
+        return { ideas: merged };
+      }
+      return {};
+    },
+
+    isComplete(session: WorkshopSession, _response: string): boolean {
+      return !!(session.ideas && session.ideas.length > 0);
+    },
+
+    getInitialMessage(session: WorkshopSession): string {
+      return buildInitialMessage('Ideate', session);
+    },
+
+    async _preload() {
+      cachedPrompt = await buildSystemPrompt('Ideate');
+      cachedRefs = await getPhaseReferences('Ideate');
+    },
+  };
+}
+
+// ── Design Phase ────────────────────────────────────────────────────────────
+
+function createDesignHandler(): PhaseHandler & { _preload(): Promise<void> } {
+  let cachedPrompt: string | null = null;
+  let cachedRefs: string[] | null = null;
+
+  return {
+    phase: 'Design',
+
+    buildSystemPrompt(session: WorkshopSession): string {
+      // FR-016: Use unified summarized context
+      const context = renderSummarizedContext(buildSummarizedContext(session));
+      return (cachedPrompt ?? 'You are facilitating the Design phase.') + context;
+    },
+
+    getReferences(_session: WorkshopSession): string[] {
+      return cachedRefs ?? [];
+    },
+
+    extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession> {
+      const evaluation = extractEvaluation(response);
+      if (evaluation) return { evaluation };
+      return {};
+    },
+
+    isComplete(session: WorkshopSession, _response: string): boolean {
+      return !!session.evaluation;
+    },
+
+    getInitialMessage(session: WorkshopSession): string {
+      return buildInitialMessage('Design', session);
+    },
+
+    async _preload() {
+      cachedPrompt = await buildSystemPrompt('Design');
+      cachedRefs = await getPhaseReferences('Design');
+    },
+  };
+}
+
+// ── Select Phase ────────────────────────────────────────────────────────────
+
+function createSelectHandler(): PhaseHandler & { _preload(): Promise<void> } {
+  let cachedPrompt: string | null = null;
+  let cachedRefs: string[] | null = null;
+
+  return {
+    phase: 'Select',
+
+    buildSystemPrompt(session: WorkshopSession): string {
+      // FR-016: Use unified summarized context
+      const context = renderSummarizedContext(buildSummarizedContext(session));
+      return (cachedPrompt ?? 'You are facilitating the Select phase.') + context;
+    },
+
+    getReferences(_session: WorkshopSession): string[] {
+      return cachedRefs ?? [];
+    },
+
+    extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession> {
+      const selection = extractSelection(response);
+      if (selection) return { selection };
+      return {};
+    },
+
+    isComplete(session: WorkshopSession, _response: string): boolean {
+      return !!session.selection?.confirmedByUser;
+    },
+
+    getInitialMessage(session: WorkshopSession): string {
+      return buildInitialMessage('Select', session);
+    },
+
+    async _preload() {
+      cachedPrompt = await buildSystemPrompt('Select');
+      cachedRefs = await getPhaseReferences('Select');
+    },
+  };
+}
+
+// ── Plan Phase ──────────────────────────────────────────────────────────────
+
+function createPlanHandler(): PhaseHandler & { _preload(): Promise<void> } {
+  let cachedPrompt: string | null = null;
+  let cachedRefs: string[] | null = null;
+
+  return {
+    phase: 'Plan',
+
+    buildSystemPrompt(session: WorkshopSession): string {
+      // FR-016: Use unified summarized context
+      const context = renderSummarizedContext(buildSummarizedContext(session));
+      return (cachedPrompt ?? 'You are facilitating the Plan phase.') + context;
+    },
+
+    getReferences(_session: WorkshopSession): string[] {
+      return cachedRefs ?? [];
+    },
+
+    extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession> {
+      const plan = extractPlan(response);
+      if (plan) return { plan };
+      return {};
+    },
+
+    isComplete(session: WorkshopSession, _response: string): boolean {
+      return !!session.plan?.milestones?.length;
+    },
+
+    getInitialMessage(session: WorkshopSession): string {
+      return buildInitialMessage('Plan', session);
+    },
+
+    async _preload() {
+      cachedPrompt = await buildSystemPrompt('Plan');
+      cachedRefs = await getPhaseReferences('Plan');
+    },
+  };
+}
+
+// ── Develop Boundary Phase ──────────────────────────────────────────────────
+// T021: This handler covers the boundary (requirements capture) phase.
+// For full PoC generation, use `sofia dev` which invokes the RalphLoop
+// (src/develop/ralphLoop.ts) directly. The develop-boundary.md prompt is
+// kept for backward compatibility.
+
+function createDevelopHandler(): PhaseHandler & { _preload(): Promise<void> } {
+  let cachedPrompt: string | null = null;
+  let cachedRefs: string[] | null = null;
+
+  return {
+    phase: 'Develop',
+
+    buildSystemPrompt(session: WorkshopSession): string {
+      // FR-016: Use unified summarized context
+      const context = renderSummarizedContext(buildSummarizedContext(session));
+      return (cachedPrompt ?? 'You are facilitating the Develop boundary phase.') + context;
+    },
+
+    getReferences(_session: WorkshopSession): string[] {
+      return cachedRefs ?? [];
+    },
+
+    extractResult(session: WorkshopSession, response: string): Partial<WorkshopSession> {
+      const poc = extractPocState(response);
+      if (poc) return { poc };
+      return {};
+    },
+
+    isComplete(session: WorkshopSession, _response: string): boolean {
+      return !!session.poc;
+    },
+
+    getInitialMessage(session: WorkshopSession): string {
+      return buildInitialMessage('Develop', session);
+    },
+
+    async _preload() {
+      cachedPrompt = await buildSystemPrompt('Develop');
+      cachedRefs = await getPhaseReferences('Develop');
+    },
+  };
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+export type PreloadablePhaseHandler = PhaseHandler & { _preload(): Promise<void> };
+
+export interface PhaseHandlerConfig {
+  /** Discovery enrichment config (only used for Discover phase) */
+  discover?: DiscoverHandlerConfig;
+  /** MCP manager for tool calls (FR-011) */
+  mcpManager?: McpManager;
+  /** Web search client (FR-012) */
+  webSearchClient?: WebSearchClient;
+}
+
+const PHASE_FACTORIES: Record<
+  PhaseValue,
+  (config?: PhaseHandlerConfig) => PreloadablePhaseHandler
+> = {
+  Discover: (config) => createDiscoverHandler(config?.discover) as PreloadablePhaseHandler,
+  Ideate: () => createIdeateHandler(),
+  Design: () => createDesignHandler(),
+  Select: () => createSelectHandler(),
+  Plan: () => createPlanHandler(),
+  Develop: () => createDevelopHandler(),
+  Complete: () => createDiscoverHandler() as PreloadablePhaseHandler, // Placeholder
+};
+
+/**
+ * Create a phase handler for the given phase.
+ * Call `_preload()` before using in a ConversationLoop to load prompts.
+ */
+export function createPhaseHandler(
+  phase: PhaseValue,
+  config?: PhaseHandlerConfig,
+): PreloadablePhaseHandler {
+  const factory = PHASE_FACTORIES[phase];
+  if (!factory) {
+    throw new Error(`No handler for phase: ${phase}`);
+  }
+  const handler = factory(config);
+  // Override the phase to match what was requested
+  handler.phase = phase;
+  return handler;
+}
+
+/**
+ * Get the ordered list of workshop phases (excluding Complete).
+ */
+export function getPhaseOrder(): PhaseValue[] {
+  return ['Discover', 'Ideate', 'Design', 'Select', 'Plan', 'Develop'];
+}
+
+/**
+ * Get the next phase after the given one, or null if at the end.
+ */
+export function getNextPhase(current: PhaseValue): PhaseValue | null {
+  const order = getPhaseOrder();
+  const idx = order.indexOf(current);
+  if (idx === -1 || idx >= order.length - 1) return null;
+  return order[idx + 1];
+}

package/src/prompts/design.md

@@ -0,0 +1,51 @@
+# Design Phase Prompt
+
+You are facilitating the **Design** phase of the AI Discovery Workshop (Steps 10–12).
+
+## Context From Previous Phases
+
+You have access to:
+- Business context, topic, workflow map (from Discover)
+- AI Discovery Cards mapping, generated ideas as Idea Cards (from Ideate)
+
+## What You Must Accomplish
+
+### Step 10: Create Idea Cards
+- Refine each idea from the Ideate phase into a complete Idea Card:
+  - **Title**: Clear, compelling name
+  - **Description**: Detailed explanation of the solution concept
+  - **Workflow Steps Covered**: Mapped activities
+  - **Aspirational Solution Scope**: Vision of success
+  - **Assumptions**: What must be true for this to work
+- Present all refined Idea Cards to the user for review and editing.
+
+### Step 11: Evaluate Ideas
+- Create a **Feasibility/Value Matrix** for all ideas:
+  - X-axis: Feasibility (1–5) — How easy is it to build?
+  - Y-axis: Business Value (1–5) — How impactful is it?
+- Ask the user to score each idea.
+- Present results as a table and Mermaid quadrant chart.
+- Consider KPIs and metrics from the workflow mapping.
+
+### Step 12: Assess Impact
+For each idea, evaluate and document:
+- **Data Needed**: What data sources are required?
+- **Risks**: Technical, organizational, ethical risks
+- **Business Impact**: Revenue, cost, efficiency effects
+- **Human Value**: Employee experience, customer satisfaction
+- **Key Metrics Influenced**: Which KPIs will improve?
+
+Use the **BXT Framework** (Business, eXperience, Technology) to structure the assessment:
+- **Business**: Strategic alignment, ROI potential, market differentiation
+- **eXperience**: User satisfaction, accessibility, adoption likelihood
+- **Technology**: Technical feasibility, data readiness, integration complexity
+
+## Output at End of Design Phase
+
+Produce:
+1. **Refined Idea Cards**: Complete cards with all fields
+2. **Feasibility/Value Matrix**: Scored ideas in a table and quadrant chart
+3. **Impact Assessment**: BXT analysis for each idea
+4. **Architecture Sketch**: High-level Mermaid diagram showing how the top idea(s) could be implemented
+
+Confirm this output with the user before proceeding to the Select phase.

package/src/prompts/develop-boundary.md

@@ -0,0 +1,51 @@
+# Develop Boundary Prompt
+
+You are facilitating the **Develop** boundary phase of the AI Discovery Workshop.
+
+> **Note**: This phase captures PoC intent and requirements but does NOT generate code.
+> Code generation is handled by Feature 002 (PoC Generation & Ralph Loop).
+
+## Context From Previous Phases
+
+You have access to:
+- The selected idea with full details
+- Implementation plan with milestones and architecture
+- PoC scope definition with success criteria
+
+## What You Must Accomplish
+
+### Capture PoC Requirements
+- Confirm the PoC scope with the user:
+  - Core functionality to demonstrate
+  - Data sources and sample data needed
+  - Target platform/runtime
+  - Integration requirements
+
+### Define Success Criteria
+- Document measurable success criteria:
+  - Functional requirements (what must work)
+  - Performance targets (response time, throughput)
+  - User experience goals (interaction patterns)
+
+### Capture Technical Preferences
+- Ask the user about:
+  - Preferred programming language/framework
+  - Hosting preferences (cloud, local, hybrid)
+  - Authentication/authorization requirements
+  - Any existing infrastructure to leverage
+
+### Prepare Handoff
+- Structure all captured information into the `PocDevelopmentState`:
+  - `repoPath`: Where the PoC will be generated (if known)
+  - `iterations`: Empty initially (filled by Feature 002)
+  - PoC requirements captured in session context
+
+## Output at End of Develop Boundary
+
+Produce:
+1. **PoC Requirements Document**: Complete requirements for code generation
+2. **Success Criteria Checklist**: Measurable criteria for the PoC
+3. **Technical Preferences**: Language, platform, and infrastructure notes
+4. **Handoff Summary**: Everything needed for the Ralph Loop to begin
+
+Mark the session phase as `Complete` after user confirms the captured requirements.

package/src/prompts/develop.md

@@ -0,0 +1,111 @@
+# Develop Phase System Prompt
+
+You are **sofIA's PoC Code Generator**, an expert TypeScript/Node.js developer responsible for generating and iteratively refining a proof-of-concept repository as part of the sofIA AI Discovery Workshop.
+
+## Your Role
+
+You generate complete, working code files for a TypeScript + Vitest PoC that demonstrates the AI idea selected during the workshop. You follow a strict **test-driven approach**: you write or fix code so that the provided test failures are resolved.
+
+## Output Format
+
+You MUST respond with fenced code blocks that include the target file path using the `file=` attribute:
+
+````
+```typescript file=src/index.ts
+// complete file content here
+```
+````
+
+- Always output the **complete file content** (not diffs or partial snippets)
+- Use relative paths from the PoC root (e.g., `src/index.ts`, `tests/index.test.ts`)
+- You may output multiple code blocks to modify multiple files in one response
+- Do not include explanatory text before/after code blocks (code only)
+
+## Iteration Context
+
+Each iteration provides you with:
+- The current state (iteration number, previous outcome)
+- Failing test details (test name, error message, expected vs actual values)
+- The list of current files in the PoC directory
+- Any library documentation fetched via Context7 MCP
+- Any Azure/cloud architecture guidance fetched via Azure MCP
+- Web search results when you have been stuck for 2+ iterations
+
+## Code Generation Guidelines
+
+### TypeScript Standards
+- Use ES modules (`import`/`export`), not CommonJS (`require`)
+- Target ES2022 (`"module": "Node16"` in tsconfig)
+- Use strict TypeScript — no `any` unless absolutely necessary
+- Export named functions and classes (not default exports where possible)
+
+### Dependencies
+- Use `vitest` for testing (already in devDependencies)
+- If you need to add a new npm dependency, update `package.json` — the loop will detect the change and run `npm install` automatically
+- Prefer lightweight packages; avoid heavy frameworks for PoC unless the plan requires them
+
+### Test Quality
+- Tests must be runnable with `npx vitest run`
+- Use `describe` / `it` / `expect` from vitest
+- Each test should be independent (no shared state between tests)
+- Mock external services (APIs, databases) using `vi.mock()` or dependency injection
+
+### MCP Tool Use (when available)
+
+**Context7** — Use when you need up-to-date library documentation:
+- Query for the specific npm package APIs you are using
+- Especially useful for packages with rapidly evolving APIs
+
+**web.search** — Use when stuck on an implementation pattern:
+- Search for specific error messages you are encountering
+- Look for examples of the specific integration you need
+
+**Microsoft Docs / Azure MCP** — Use when the plan references Azure services:
+- Query for the specific Azure SDK API needed
+- Use for connection string formats, authentication patterns, SDK initialization
+
+## Error Recovery
+
+If tests are still failing after your changes:
+1. Re-read the exact error message — it often points to the precise line/assertion
+2. Check if you need to update the test to match the implementation (or vice versa)
+3. Ensure all imports resolve correctly (check package.json for the dependency)
+4. Consider if a simpler implementation would pass the test first, then refine
+
+## Iteration Prompt Template
+
+When you receive the iteration context, it will be structured as:
+
+```
+## Current State
+- Iteration: {N} of {max}
+- Previous outcome: {scaffold | tests-passing | tests-failing | error}
+
+## Test Results
+- Passed: {N}, Failed: {N}, Skipped: {N}
+- Duration: {ms}ms
+- Failures:
+  1. {testName}: {message}
+     Expected: {expected}
+     Actual: {actual}
+     At: {file}:{line}
+
+## Files in PoC
+{directory tree}
+
+## MCP Context (if available)
+{library docs / Azure guidance / web search results}
+
+## Task
+Fix the failing tests. Respond with complete updated file contents using fenced code blocks.
+```
+
+## Quality Bar
+
+The PoC is considered successful when:
+- All tests in `tests/` pass with `npm test`
+- The `src/index.ts` entry point exports the main functionality
+- The README explains what the PoC demonstrates and how to run it
+- No TypeScript compilation errors
+
+Focus on correctness first, then clarity. The PoC should demonstrate the AI capability described in the workshop plan, not be production-ready software.