sofia-cli 0.1.1

package/specs/003-mcp-transport-integration/contracts/context-enricher.md

@@ -0,0 +1,220 @@
+# Contract: MCP Context Enricher (Real Integration)
+
+**Feature**: 003-mcp-transport-integration  
+**Module**: `src/develop/mcpContextEnricher.ts`  
+**Status**: Authoritative design document (replaces stub behavior from Feature 002)
+
+---
+
+## Overview
+
+`McpContextEnricher` conditionally queries three MCP servers to enrich LLM iteration prompts:
+
+1. **Context7** — library documentation for PoC dependencies
+2. **Azure MCP** — architecture guidance when plan references Azure services
+3. **Web Search** — solutions to failing tests when stuck (2+ consecutive iterations)
+
+All three methods use real MCP `callTool()` invocations (replacing hardcoded strings). All degrade gracefully when their respective servers are unavailable.
+
+---
+
+## queryContext7() Contract
+
+### When Invoked
+
+Only when:
+- `mcpManager.isAvailable('context7')` is `true`
+- `dependencies.length > 0`
+
+### Tool Call Sequence (per dependency)
+
+**Step 1: Resolve library ID**
+
+```typescript
+mcpManager.callTool('context7', 'resolve-library-id', {
+  libraryName: dep,  // e.g., 'express', 'zod'
+}, { timeoutMs: 30_000 })
+```
+
+Response field extraction for `libraryId`:
+- `response.libraryId` (primary)
+- `response.id` (fallback)
+- If neither present: skip to fallback link (do not throw)
+
+**Step 2: Query docs (only if libraryId resolved)**
+
+```typescript
+mcpManager.callTool('context7', 'query-docs', {
+  libraryId,  // e.g., '/expressjs/express'
+  topic: dep, // hint to focus the query
+}, { timeoutMs: 30_000 })
+```
+
+Response field extraction for documentation text:
+- `response.content` (string, primary)
+- `response.text` (string, fallback)
+- If neither present: use fallback link
+
+### Dependency Filter Rules
+
+| Dependency | Skip? |
+|------------|-------|
+| Starts with `@types/` | ✅ Skip (type-only package) |
+| `typescript` | ✅ Skip (well-known, no runtime docs needed) |
+| `vitest` | ✅ Skip (test-only) |
+| `node` | ✅ Skip |
+| First 5 non-skipped deps only | Process (others skipped to limit tokens) |
+
+### Fallback
+
+When Context7 is unavailable OR a dependency resolution fails:
+```
+- **{dep}**: See https://www.npmjs.com/package/{dep} for API documentation
+```
+
+### Output Format
+
+```
+- **express**:
+{documentation text from Context7}
+
+- **zod**:
+{documentation text from Context7}
+```
+
+---
+
+## queryAzureMcp() Contract
+
+### When Invoked
+
+Only when:
+- `mcpManager.isAvailable('azure')` is `true`
+- `architectureNotes` contains at least one Azure keyword (existing detection logic)
+
+### Tool Call
+
+```typescript
+mcpManager.callTool('azure', 'documentation', {
+  query: `Best practices for ${detectedKeywords.join(', ')} in Azure`,
+}, { timeoutMs: 30_000 })
+```
+
+Response field extraction:
+- `response.content` (string, primary)
+- `response.text` (string, fallback)
+- If neither: fall through to static guidance
+
+### Fallback (when Azure MCP unavailable or call fails)
+
+Return static guidance string (existing behavior):
+```
+Detected Azure services: {detected.join(', ')}
+Use the @azure/identity DefaultAzureCredential for authentication.
+Prefer connection strings from environment variables (never hardcode).
+```
+
+---
+
+## queryWebSearch() Contract
+
+### When Invoked
+
+Only when:
+- `isWebSearchConfigured()` returns `true` (env var `AZURE_AI_FOUNDRY_ENDPOINT` set)
+- `stuckIterations >= 2`
+- `failingTests.length > 0`
+
+### Invocation Priority
+
+1. **Prefer MCP-based search** (if `mcpManager.isAvailable('websearch')`):
+   ```typescript
+   mcpManager.callTool('websearch', 'search', {
+     query: `how to fix: ${failingTests.slice(0, 3).join('; ')}`,
+   }, { timeoutMs: 30_000 })
+   ```
+   Response: `response.content` or `response.text`
+
+2. **Fall back to Azure AI Foundry bridge** (existing `webSearch.ts` implementation):
+   ```typescript
+   // Already implemented in src/mcp/webSearch.ts
+   webSearchClient.search(query)
+   ```
+
+### Output Format
+
+When results are returned:
+```
+Search results for: "{query}"
+
+{formatted search results}
+```
+
+When no results available:
+```
+Web search for: "{query}" — no results available in this environment.
+```
+
+---
+
+## enrich() Orchestration Contract
+
+```typescript
+async enrich(options: EnricherOptions): Promise<EnrichedContext>
+```
+
+### Execution Order
+
+1. Context7 query (parallel-safe, independent)
+2. Azure MCP query (parallel-safe, independent)
+3. Web search (only if stuck — gated by `stuckIterations >= 2`)
+
+**Parallelism**: Queries 1 and 2 MAY be run concurrently with `Promise.allSettled()` to reduce latency. Web search runs sequentially after both to avoid unnecessary API calls when Context7 already unblocks the LLM.
+
+### EnrichedContext Assembly
+
+```typescript
+{
+  libraryDocs,      // from Context7 (undefined if unavailable)
+  azureGuidance,    // from Azure MCP (undefined if unavailable)
+  webSearchResults, // from web search (undefined if not stuck or unavailable)
+  combined: parts.join('\n\n'),  // non-empty parts assembled as markdown sections
+}
+```
+
+---
+
+## Graceful Degradation Matrix
+
+| Server | Unavailable Behavior |
+|--------|---------------------|
+| `context7` | Returns npm links instead of real docs. `combined` omits Context7 section. |
+| `azure` | Returns static guidance string. `combined` uses static string. |
+| `websearch` | Falls back to Azure AI Foundry bridge. If also unavailable, returns placeholder string. |
+| All unavailable | `combined` is empty string. Ralph Loop continues with LLM's baseline knowledge. |
+
+---
+
+## Acceptance Tests
+
+| Test | Type | Description |
+|------|------|-------------|
+| `queryContext7 calls resolve-library-id for each dependency` | unit | Verify tool calls dispatched |
+| `queryContext7 uses libraryId from response.libraryId` | unit | Primary field extraction |
+| `queryContext7 uses libraryId from response.id as fallback` | unit | Fallback field extraction |
+| `queryContext7 skips @types/* dependencies` | unit | Filter rule |
+| `queryContext7 skips typescript and vitest dependencies` | unit | Filter rule |
+| `queryContext7 processes max 5 non-skipped deps` | unit | Limit rule |
+| `queryContext7 returns npm link when resolve-library-id fails` | unit | Graceful degradation |
+| `queryContext7 returns npm link when libraryId missing` | unit | No libraryId in response |
+| `queryContext7 returns undefined when context7 unavailable` | unit | `isAvailable('context7')` false |
+| `queryAzureMcp calls documentation tool with detected keywords` | unit | Tool dispatched with correct query |
+| `queryAzureMcp extracts content from response.content` | unit | Primary field |
+| `queryAzureMcp falls back to static guidance on callTool error` | unit | Graceful degradation |
+| `queryAzureMcp returns undefined when azure unavailable` | unit | `isAvailable('azure')` false |
+| `queryWebSearch calls websearch.search when server available` | unit | MCP tool dispatch |
+| `queryWebSearch uses Azure AI Foundry bridge as fallback` | unit | Bridge used when MCP unavailable |
+| `queryWebSearch returns undefined when not configured` | unit | `isWebSearchConfigured()` false |
+| `enrich returns combined string with all available contexts` | unit | All three sections present |
+| `enrich skips web search when stuckIterations < 2` | unit | Gate enforced |
+| `enrich handles all servers unavailable gracefully` | unit | Empty combined, no throws |

package/specs/003-mcp-transport-integration/contracts/discovery-enricher.md

@@ -0,0 +1,267 @@
+# Contract: Discovery Phase Enrichment
+
+**Feature**: 003-mcp-transport-integration  
+**Modules**: `src/phases/discoveryEnricher.ts`, `src/shared/schemas/session.ts`  
+**Status**: Authoritative design document
+
+---
+
+## Overview
+
+After the user provides company and team information in Step 1 of the discovery workshop, the system optionally enriches the session with:
+1. **Web search results** — recent company news, competitor activity, industry trends
+2. **WorkIQ insights** — internal team collaboration patterns and expertise (requires explicit user consent and WorkIQ availability)
+
+Enrichment is stored in `WorkshopSession.discovery.enrichment` and is referenced by subsequent phases (ideation, planning) to improve PoC relevance.
+
+---
+
+## DiscoveryEnricher Interface
+
+```typescript
+// src/phases/discoveryEnricher.ts
+
+export interface DiscoveryEnricherOptions {
+  /** Company and team summary from Step 1 (used to build search queries) */
+  companySummary: string;
+  /** MCP manager for WorkIQ tool calls */
+  mcpManager: McpManager;
+  /** IO for permission prompts and progress messages */
+  io: LoopIO;
+  /** Activity spinner for visual feedback */
+  spinner?: ActivitySpinner;
+  /** Web search client (defaults to production webSearch module) */
+  webSearchClient?: WebSearchClient;
+}
+
+export class DiscoveryEnricher {
+  /**
+   * Run the full enrichment flow: web search + optional WorkIQ.
+   * Returns a populated DiscoveryEnrichment object (may have empty fields
+   * if all enrichment sources are unavailable).
+   */
+  async enrich(options: DiscoveryEnricherOptions): Promise<DiscoveryEnrichment>;
+
+  /**
+   * Run only the web search enrichment step.
+   * Does not prompt the user.
+   */
+  async enrichFromWebSearch(
+    companySummary: string,
+    webSearchClient: WebSearchClient,
+  ): Promise<Partial<DiscoveryEnrichment>>;
+
+  /**
+   * Run only the WorkIQ enrichment step.
+   * Prompts the user for consent before making any WorkIQ calls.
+   * Returns empty partial if user declines or WorkIQ unavailable.
+   */
+  async enrichFromWorkIQ(
+    companySummary: string,
+    mcpManager: McpManager,
+    io: LoopIO,
+  ): Promise<Partial<DiscoveryEnrichment>>;
+}
+```
+
+---
+
+## enrich() Orchestration Flow
+
+```
+Step 1 input collected
+      │
+      ▼
+[Web Search Available?] ──no──► skip, continue
+      │ yes
+      ▼
+io.writeActivity('Searching for recent company and industry context...')
+spinner.start('Enriching discovery context')
+      │
+      ▼
+enrichFromWebSearch(companySummary)
+      │
+      ▼
+[WorkIQ MCP Available?] ──no──► skip to session save
+      │ yes
+      ▼
+io.writeActivity('WorkIQ is available — it can analyze your team's internal context.')
+io.prompt('May sofIA query WorkIQ for team insights? [y/N]')
+      │
+      ├── no/timeout ──► skip WorkIQ
+      │
+      ▼ yes
+enrichFromWorkIQ(companySummary)
+      │
+      ▼
+Merge partial enrichments → DiscoveryEnrichment
+Set enrichment.enrichedAt = new Date().toISOString()
+Set enrichment.sourcesUsed = ['websearch'?, 'workiq'?]
+session.discovery.enrichment = enrichment
+onSessionUpdate(session)
+spinner.stop()
+io.writeActivity('Discovery context enriched ✓')
+```
+
+---
+
+## enrichFromWebSearch() Contract
+
+### Web Search Query Strategy
+
+Three sequential queries (or as many as return results before timeout):
+
+| Query | Purpose |
+|-------|---------|
+| `"${company name} recent news 2024 2025"` | Company news |
+| `"${company name} competitors market 2024"` | Competitor activity |
+| `"${industry or domain} AI trends 2025"` | Industry trends |
+
+The company name and industry are extracted from `companySummary` via simple keyword heuristic (first quoted proper noun, or first capitalized multi-word sequence).
+
+### Response Mapping
+
+```typescript
+// From WebSearchResult:
+{
+  companyNews: results[0]?.results.map(r => `${r.title}: ${r.snippet}`),
+  competitorInfo: results[1]?.results.map(r => `${r.title}: ${r.snippet}`),
+  industryTrends: results[2]?.results.map(r => `${r.title}: ${r.snippet}`),
+  webSearchResults: [results].flatMap(r => r.results).map(r => r.snippet).join('\n'),
+}
+```
+
+Array fields are capped at 10 items each.
+
+### Graceful Degradation
+
+| Condition | Behavior |
+|-----------|---------|
+| Web search not configured (`isWebSearchConfigured()` false) | Return `{}` immediately, no prompt shown |
+| `WebSearchResult.degraded` is `true` | Return `{}` with no error surfaced to user |
+| Individual query throws | Log debug, continue with remaining queries |
+
+---
+
+## enrichFromWorkIQ() Contract
+
+### Permission Gate
+
+**REQUIRED**: Show a consent prompt before any WorkIQ call:
+
+```
+sofIA can query WorkIQ to analyze your team's internal context
+(meeting patterns, expertise areas, documentation gaps).
+This requires access to your Microsoft 365 tenant.
+
+May sofIA access WorkIQ for team insights? (y/N)
+```
+
+If the user responds `n` or `N` (or presses Enter for the default):
+- Return `{}` immediately
+- Do NOT call any WorkIQ tool
+- Log at `info` level: `'User declined WorkIQ enrichment'`
+
+### WorkIQ Tool Call
+
+```typescript
+mcpManager.callTool('workiq', 'analyze_team', {
+  summary: companySummary,
+  focus: ['expertise', 'collaboration', 'documentation'],
+}, { timeoutMs: 30_000 })
+```
+
+Response field extraction:
+- `response.teamExpertise` → `workiqInsights.teamExpertise`
+- `response.collaborationPatterns` → `workiqInsights.collaborationPatterns`
+- `response.documentationGaps` → `workiqInsights.documentationGaps`
+- `response.insights` (fallback, split by newline) → all three fields
+
+### Graceful Degradation
+
+| Condition | Behavior |
+|-----------|---------|
+| `mcpManager.isAvailable('workiq')` false | Return `{}`, no prompt shown, log info `'WorkIQ not available'` |
+| `callTool` throws `auth-failure` | Return `{}`, show message: `'WorkIQ authentication required — skipping team insights'` |
+| `callTool` throws timeout/connection error | Return `{}`, log warn, show message: `'WorkIQ temporarily unavailable — skipping team insights'` |
+| User declines consent | Return `{}`, no WorkIQ calls |
+
+---
+
+## Session Schema Extension
+
+```typescript
+// src/shared/schemas/session.ts
+
+// DiscoveryEnrichmentSchema (new)
+export const DiscoveryEnrichmentSchema = z.object({
+  webSearchResults: z.string().optional(),
+  companyNews: z.array(z.string()).max(10).optional(),
+  competitorInfo: z.array(z.string()).max(10).optional(),
+  industryTrends: z.array(z.string()).max(10).optional(),
+  workiqInsights: z.object({
+    teamExpertise: z.array(z.string()).max(10).optional(),
+    collaborationPatterns: z.array(z.string()).max(10).optional(),
+    documentationGaps: z.array(z.string()).max(10).optional(),
+  }).optional(),
+  enrichedAt: z.string().datetime().optional(),
+  sourcesUsed: z.array(z.string()).optional(),
+});
+
+// DiscoveryStateSchema (modified — add enrichment field)
+export const DiscoveryStateSchema = z.object({
+  // ... existing fields ...
+  enrichment: DiscoveryEnrichmentSchema.optional(),
+});
+```
+
+**Backward compatibility**: `enrichment` is optional. Sessions from Feature 001/002 parse without errors.
+
+---
+
+## Downstream Phase Usage
+
+When `session.discovery.enrichment` is non-empty, the enrichment is injected into the ideation and planning phase prompts:
+
+```markdown
+## Discovery Context (from market research)
+
+**Recent Company News**:
+- {companyNews[0]}
+- {companyNews[1]}
+
+**Competitive Landscape**:
+- {competitorInfo[0]}
+
+**Industry Trends**:
+- {industryTrends[0]}
+
+**Internal Team Context** (from WorkIQ):
+- Expertise: {workiqInsights.teamExpertise.join(', ')}
+- Collaboration: {workiqInsights.collaborationPatterns.join(', ')}
+```
+
+This injection is the responsibility of the ideation/planning phase prompt builder, not `DiscoveryEnricher`.
+
+---
+
+## Acceptance Tests
+
+| Test | Type | Description |
+|------|------|-------------|
+| `enrich runs web search when configured` | unit | webSearchClient called with company queries |
+| `enrich skips web search when not configured` | unit | Returns without querying |
+| `enrich shows WorkIQ prompt when available` | unit | io.prompt called before WorkIQ |
+| `enrich calls WorkIQ when user consents` | unit | callTool('workiq', 'analyze_team', ...) dispatched |
+| `enrich skips WorkIQ when user declines` | unit | No callTool for workiq |
+| `enrich skips WorkIQ when not available` | unit | No prompt shown, no callTool |
+| `enrich stores enrichedAt timestamp` | unit | ISO string set |
+| `enrich stores sourcesUsed correctly` | unit | Reflects which sources ran |
+| `enrichFromWebSearch builds three queries from companySummary` | unit | Query construction |
+| `enrichFromWebSearch caps array fields at 10 items` | unit | Boundary check |
+| `enrichFromWebSearch returns empty on degraded search` | unit | Graceful degradation |
+| `enrichFromWorkIQ returns empty on auth-failure` | unit | Auth error handling |
+| `enrichFromWorkIQ returns empty on timeout` | unit | Timeout handling |
+| `enrichFromWorkIQ returns empty on user decline` | unit | No-consent path |
+| `discoveryEnricher saves enrichment to session via onSessionUpdate` | integration | Session persistence |
+| `phaseHandler injects enrichment into ideation prompt` | integration | Downstream usage |

package/specs/003-mcp-transport-integration/contracts/github-adapter.md

@@ -0,0 +1,149 @@
+# Contract: GitHub MCP Adapter (Real Integration)
+
+**Feature**: 003-mcp-transport-integration  
+**Module**: `src/develop/githubMcpAdapter.ts`  
+**Status**: Authoritative design document (replaces stub behavior from Feature 002)
+
+---
+
+## Overview
+
+`GitHubMcpAdapter` wraps two GitHub MCP tool calls — `create_repository` and `push_files` — and applies graceful degradation when the GitHub MCP server is unavailable. This contract defines the real behavior replacing the stubs introduced in Feature 002.
+
+---
+
+## createRepository()
+
+### Call
+
+```typescript
+mcpManager.callTool('github', 'create_repository', {
+  name: options.name,          // repository name (slug)
+  description: options.description ?? '',
+  private: options.private ?? true,
+}, { timeoutMs: 60_000 })
+```
+
+### Response Mapping
+
+The GitHub MCP `create_repository` tool returns a JSON object representing the created repository. Field extraction priority:
+
+| Field to Extract | Try These Response Keys (in order) |
+|------------------|------------------------------------|
+| `repoUrl` | `response.html_url`, `response.url`, `response.clone_url` |
+| `repoName` | `response.name`, `response.full_name`, or fallback to `options.name` |
+
+### Success Return
+
+```typescript
+{ available: true, repoUrl: 'https://github.com/org/repo', repoName: 'repo' }
+```
+
+### Failure Return
+
+```typescript
+{ available: false, reason: '<error message>' }
+```
+
+### Conditions Returning `{ available: false }`
+
+| Condition | Reason Logged |
+|-----------|---------------|
+| `isAvailable()` is `false` | `'GitHub MCP not available'` |
+| `callTool` throws `McpTransportError` | Error message from transport |
+| Response missing `html_url`, `url`, and `clone_url` | `'MCP response missing repository URL'` |
+
+---
+
+## pushFiles()
+
+### Pre-processing (ralphLoop.ts responsibility)
+
+Before calling `pushFiles()`, the caller (Ralph Loop) MUST:
+1. Read each file's content from disk using `readFile(resolve(outputDir, filePath), 'utf-8')`.
+2. Skip files that fail to read — log a warning and omit them from the push.
+3. Skip files outside the output directory (path traversal check using `isPathWithinDirectory`).
+
+The `PushFilesOptions.files` array MUST contain actual file content — never empty strings.
+
+### Call
+
+```typescript
+mcpManager.callTool('github', 'push_files', {
+  owner: extractOwnerFromUrl(options.repoUrl),   // extracted from repo URL
+  repo: extractRepoFromUrl(options.repoUrl),      // extracted from repo URL
+  branch: options.branch ?? 'main',
+  message: options.commitMessage,
+  files: options.files.map(f => ({
+    path: f.path,
+    content: f.content,   // actual file content (UTF-8 text)
+  })),
+}, { timeoutMs: 60_000 })
+```
+
+### Response Mapping
+
+| Field to Extract | Try These Response Keys |
+|-----------------|------------------------|
+| `commitSha` | `response.sha`, `response.commit.sha` |
+
+### Success Return
+
+```typescript
+{ available: true, commitSha: 'abc123def456' }
+// commitSha is optional — may be undefined if the server doesn't return it
+```
+
+### Failure Return
+
+```typescript
+{ available: false, reason: '<error message>' }
+```
+
+---
+
+## Post-Scaffold Push (RalphLoop Responsibility)
+
+The Ralph Loop is responsible for an **initial scaffold push** immediately after npm install completes and before entering the iteration loop:
+
+```
+scaffold → npm install → push scaffold files → iteration 1 → iteration 2 → ...
+```
+
+**When to push**: Only if `githubAdapter.isAvailable()` AND a repo was created (non-null `repoUrl`).
+
+**Files to push**: All `scaffoldResult.createdFiles` (relative paths within `outputDir`).
+
+**Content**: Read from disk at `resolve(outputDir, filePath)` — same pattern as iteration pushes.
+
+**On failure**: Log warning and continue — scaffold push failure is not fatal.
+
+---
+
+## Graceful Degradation Rules
+
+1. When GitHub MCP is unavailable (`isAvailable()` returns `false`): both methods return `{ available: false }` immediately without attempting any tool call.
+2. When a tool call throws any error: catch, log at `warn` level, return `{ available: false, reason: err.message }`.
+3. When `createRepository` fails: the Ralph Loop continues with local-only output (no remote repo).
+4. When `pushFiles` fails: the local PoC is intact; the remote repo may be stale. Log the failure with iteration number.
+
+---
+
+## Acceptance Tests
+
+| Test | Type | Description |
+|------|------|-------------|
+| `createRepository dispatches create_repository tool call` | unit | Verify callTool called with correct server/tool/args |
+| `createRepository extracts repoUrl from html_url response field` | unit | Mock response with `html_url` |
+| `createRepository extracts repoUrl from url response field` | unit | Mock response with `url` (fallback) |
+| `createRepository returns available:false when MCP unavailable` | unit | `isAvailable()` returns false |
+| `createRepository returns available:false on callTool error` | unit | Transport throws |
+| `createRepository returns available:false when response has no URL` | unit | Mock response missing all URL fields |
+| `pushFiles dispatches push_files with actual content` | unit | Verify `files[n].content` is non-empty string |
+| `pushFiles extracts commitSha from response.sha` | unit | Mock response with `sha` |
+| `pushFiles extracts commitSha from response.commit.sha` | unit | Mock response with nested sha |
+| `pushFiles returns available:false when MCP unavailable` | unit | `isAvailable()` returns false |
+| `pushFiles returns available:false on callTool error` | unit | Transport throws |
+| `ralphLoop pushFiles sends non-empty file content` | integration | Verify content !== '' for all pushed files |
+| `ralphLoop pushes scaffold files after npm install` | integration | Scaffold push happens before iteration 1 |
+| `ralphLoop skips out-of-bounds paths before pushFiles` | integration | Path traversal attempt is logged and skipped |