sofia-cli 0.1.1

package/specs/006-workshop-extraction-fixes/data-model.md

@@ -0,0 +1,149 @@
+# Data Model: Workshop Phase Extraction & Tool Wiring Fixes
+
+**Feature**: 006-workshop-extraction-fixes  
+**Date**: 2026-03-04
+
+## New Entities
+
+### SummarizedPhaseContext
+
+A compact, deterministic projection of all structured session fields from prior phases. Used to build the system prompt for each new phase, replacing ad-hoc per-handler context injection.
+
+| Field                  | Type                               | Source                                                                       | Description                                               |
+| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `businessSummary`      | `string?`                          | `session.businessContext.businessDescription`                                | Company/business description from Discover                |
+| `challenges`           | `string[]?`                        | `session.businessContext.challenges`                                         | Key challenges from Discover                              |
+| `topicArea`            | `string?`                          | `session.topic.topicArea`                                                    | Chosen workshop focus area                                |
+| `workflowSteps`        | `string[]?`                        | `session.workflow.activities[].name`                                         | Activity names from the workflow map                      |
+| `enrichmentHighlights` | `string[]?`                        | `session.discovery.enrichment.{industryTrends, companyNews, workiqInsights}` | Web search and WorkIQ highlights from Discover enrichment |
+| `ideaSummaries`        | `Array<{id, title, description}>?` | `session.ideas[]`                                                            | Idea card summaries from Ideate                           |
+| `evaluationSummary`    | `string?`                          | `session.evaluation`                                                         | Evaluation method + idea count from Design                |
+| `selectionSummary`     | `string?`                          | `session.selection`                                                          | Selected idea ID + rationale from Select                  |
+| `planMilestones`       | `string[]?`                        | `session.plan.milestones[].title`                                            | Milestone titles from Plan                                |
+| `architectureNotes`    | `string?`                          | `session.plan.architectureNotes`                                             | Architecture description from Plan                        |
+
+**Relationships**: Pure projection from `WorkshopSession` fields. No persistence — generated on-the-fly at each phase transition.
+
+**Validation**: No schema validation needed (it's a rendering utility). Each field is optional; missing fields are omitted from the rendered output.
+
+---
+
+### PhaseSummarizationPrompt
+
+The system prompt sent to the LLM during the post-phase summarization call. Phase-specific.
+
+| Field               | Type         | Description                                                                      |
+| ------------------- | ------------ | -------------------------------------------------------------------------------- |
+| `phase`             | `PhaseValue` | Which phase this summarization targets                                           |
+| `systemPrompt`      | `string`     | Loaded from `src/prompts/summarize/{phase}-summary.md`                           |
+| `targetSchemaShape` | `string`     | JSON schema example embedded in the prompt (matched to Zod schema)               |
+| `phaseTranscript`   | `string`     | Full conversation transcript for the phase (user + assistant turns concatenated) |
+
+**Relationships**: One summarization prompt per phase (6 total, though Discover may not need one since `businessContext` extraction already works). The prompt template references the Zod schema from `session.ts`.
+
+---
+
+### McpWorkshopConfig
+
+Configuration passed from `workshopCommand.ts` to phase handler factories.
+
+| Field             | Type               | Description                         |
+| ----------------- | ------------------ | ----------------------------------- |
+| `mcpManager`      | `McpManager?`      | MCP manager instance for tool calls |
+| `webSearchClient` | `WebSearchClient?` | Foundry web search client           |
+
+**Relationships**: Extends the existing `PhaseHandlerConfig`. Passed to `createPhaseHandler()` which distributes to individual handler factories.
+
+---
+
+## Modified Entities
+
+### WorkshopSession (existing — no schema changes)
+
+No fields are added or modified on the session schema. All 29 FRs operate on **existing** session fields:
+
+- `businessContext` (Discover)
+- `workflow` (Discover)
+- `ideas` (Ideate)
+- `evaluation` (Design)
+- `selection` (Select)
+- `plan` (Plan)
+- `poc` (Develop)
+- `turns[]` (all phases)
+- `discovery.enrichment` (Discover enrichment)
+
+The only change is that these fields will now be **reliably populated** thanks to the summarization call fallback.
+
+### PhaseHandlerConfig (existing — extended)
+
+Currently:
+
+```
+{ discover?: DiscoverHandlerConfig }
+```
+
+After:
+
+```
+{ discover?: DiscoverHandlerConfig, mcpManager?: McpManager, webSearchClient?: WebSearchClient }
+```
+
+### ConversationLoopOptions (existing — extended)
+
+Added field:
+
+- `infiniteSessions?: { enabled?: boolean, backgroundCompactionThreshold?: number, bufferExhaustionThreshold?: number }` — forwarded to the SDK session for context compaction.
+
+---
+
+## State Transitions
+
+No new state transitions. The existing phase progression is unchanged:
+
+```
+Discover → Ideate → Design → Select → Plan → Develop → Complete
+```
+
+Each transition now has an additional step between the conversation loop completing and the decision gate:
+
+```
+ConversationLoop exits
+  → Post-phase summarization call (if structured fields still null)
+  → Session persisted with extracted data
+  → Decision gate shown to user
+```
+
+---
+
+## Data Flow Diagram
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
+│ Phase N conv │────▸│ extractResult│────▸│ session field set?│
+│  loop exits  │     │ (per-turn)   │     │   (e.g. ideas)   │
+└──────┬───────┘     └──────────────┘     └────────┬─────────┘
+       │                                           │
+       │                                    yes ───┴─── no
+       │                                    │           │
+       │                                    │     ┌─────▼──────────┐
+       │                                    │     │ Summarization  │
+       │                                    │     │ LLM call       │
+       │                                    │     │ (new session)  │
+       │                                    │     └──────┬─────────┘
+       │                                    │            │
+       │                                    │     ┌──────▼─────────┐
+       │                                    │     │ extractResult  │
+       │                                    │     │ on summary     │
+       │                                    │     └──────┬─────────┘
+       │                                    │            │
+       ▼                                    ▼            ▼
+┌──────────────────────────────────────────────────────────┐
+│              Session persisted with data                  │
+└──────────────────────────────────────────────────────────┘
+       │
+       ▼
+┌──────────────┐     ┌───────────────────────┐
+│ Context      │────▸│ Phase N+1 starts with │
+│ summarizer   │     │ SummarizedPhaseContext │
+└──────────────┘     └───────────────────────┘
+```

package/specs/006-workshop-extraction-fixes/plan.md

@@ -0,0 +1,123 @@
+# Implementation Plan: Workshop Phase Extraction & Tool Wiring Fixes
+
+**Branch**: `006-workshop-extraction-fixes` | **Date**: 2026-03-04 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/006-workshop-extraction-fixes/spec.md`
+
+## Summary
+
+Fix five systemic bugs discovered during the Zava Industries full-session assessment that prevent sofIA from: (1) reliably extracting structured data from LLM responses across all workshop phases, (2) recognizing web search configuration when `.env` is loaded after module import, (3) wiring MCP tools into the workshop flow, (4) managing context window growth across multi-phase sessions, and (5) exporting all phases regardless of structured data availability. The primary technical approach is a post-phase summarization LLM call for extraction, lazy env checking, McpManager/WebSearchClient wiring in workshopCommand, context summarization instead of raw turn injection, and conversation-fallback export generation.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.x on Node.js 22 LTS  
+**Primary Dependencies**: `@github/copilot-sdk`, `zod` (schema validation), `marked`/`marked-terminal` (markdown rendering), `pino` (logging), `commander` (CLI), `dotenv` (.env loading)  
+**Storage**: Single JSON file per session in `.sofia/sessions/<sessionId>.json`  
+**Testing**: Vitest (unit + integration + live); 709 unit tests, 99 integration tests currently passing  
+**Target Platform**: Linux/macOS/Windows (Node.js CLI)  
+**Project Type**: CLI application  
+**Performance Goals**: Phase summarization call must complete within 60 seconds; context summary generation adds <500ms to phase transitions  
+**Constraints**: Copilot SDK `sendAndWait()` has a 120s timeout; session JSON files can grow to 100KB+ for multi-phase sessions  
+**Scale/Scope**: 6 workshop phases, ~10–15 conversation turns per phase, 29 functional requirements across 6 categories
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+| Gate                            | Status  | Evidence                                                                                                                                                                         |
+| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Outcome-first discovery**     | ✅ PASS | All 5 bugs directly prevent workshop artifacts from reaching users. SC-006 targets 75%+ assessment score (up from 53%).                                                          |
+| **Secure-by-default**           | ✅ PASS | No new secrets/PII handling. `.env` loading respects existing `override: false` policy. MCP calls follow existing least-privilege patterns.                                      |
+| **Node.js + TypeScript**        | ✅ PASS | All changes are TypeScript, aligned with existing Copilot SDK patterns. No new runtime dependencies required.                                                                    |
+| **MCP-first**                   | ✅ PASS | FR-011–FR-015 wire existing MCP servers (Context7, Azure, WorkIQ) into workshop phases. No ad-hoc HTTP calls introduced.                                                         |
+| **Test-first (NON-NEGOTIABLE)** | ✅ PASS | Each FR group will be implemented via Red→Green→Review. Failing tests written first for: summarization call, lazy env check, export fallback, context summarization, MCP wiring. |
+| **CLI transparency**            | ✅ PASS | Summarization call progress surfaced via existing spinner. Export generates files for all phases. Phase boundary prompts improve UX predictability.                              |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-workshop-extraction-fixes/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+│   └── summarization-and-export.md
+├── checklists/
+│   └── requirements.md  # Quality checklist
+└── tasks.md             # Phase 2 output (NOT created by /speckit.plan)
+```
+
+### Source Code (files modified or created)
+
+```text
+src/
+├── cli/
+│   ├── workshopCommand.ts      # FR-011,012,012a: wire McpManager + WebSearchClient; FR-010: ensure loadEnvFile runs first
+│   └── developCommand.ts       # FR-010: ensure loadEnvFile runs first
+├── loop/
+│   ├── conversationLoop.ts     # FR-001,006: add postPhaseSummarize(); FR-016–018: context summarization; FR-007b,c: phase boundary injection; FR-019a: timeout fallback
+│   └── phaseSummarizer.ts      # NEW: summarization LLM call utility (FR-001–005)
+├── mcp/
+│   └── webSearch.ts            # FR-008,009: make isWebSearchConfigured() lazy
+├── phases/
+│   ├── phaseExtractors.ts      # FR-007: multi-JSON-block extraction; FR-007a: Mermaid extraction
+│   ├── phaseHandlers.ts        # FR-013,014: Design/Plan accept MCP config; FR-007b: phase boundary in buildSystemPrompt
+│   └── contextSummarizer.ts    # NEW: build SummarizedPhaseContext from session fields (FR-016–018)
+├── sessions/
+│   └── exportWriter.ts         # FR-020–024: conversation fallback export, summary.json enhancements
+└── prompts/
+    └── summarize/              # NEW: per-phase summarization prompts (FR-002)
+        ├── ideate-summary.md
+        ├── design-summary.md
+        ├── select-summary.md
+        ├── plan-summary.md
+        └── develop-summary.md
+
+tests/
+├── unit/
+│   ├── loop/
+│   │   ├── phaseSummarizer.spec.ts         # Tests for summarization call
+│   │   └── contextSummarizer.spec.ts       # Tests for context summarization
+│   ├── mcp/
+│   │   └── webSearch.spec.ts               # Tests for lazy isWebSearchConfigured
+│   ├── phases/
+│   │   ├── phaseExtractors.spec.ts         # Tests for multi-block extraction + Mermaid
+│   │   └── phaseHandlers.spec.ts           # Tests for phase boundary injection, MCP config
+│   └── sessions/
+│       └── exportWriter.spec.ts            # Tests for conversation fallback export
+├── integration/
+│   ├── summarizationFlow.spec.ts           # Integration test: full summarize pipeline
+│   └── exportFallbackFlow.spec.ts          # Integration test: export with null structured data
+└── live/
+    └── zavaFullWorkshop.spec.ts            # Updated Zava assessment test (regression)
+```
+
+**Structure Decision**: Single-project CLI structure preserved. Two new modules (`phaseSummarizer.ts`, `contextSummarizer.ts`) are extracted to avoid bloating `conversationLoop.ts`. New summarization prompts are placed under `src/prompts/summarize/` following the existing prompt organization pattern.
+
+## Complexity Tracking
+
+> No constitution violations. All gates pass.
+
+## Constitution Re-Check (Post-Design)
+
+| Gate                            | Status  | Evidence                                                                                                                                                                                                  |
+| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Outcome-first discovery**     | ✅ PASS | Summarization call directly enables structured artifact extraction → export → `sofia dev` → user value. All changes tie to the 53%→75% assessment improvement goal.                                       |
+| **Secure-by-default**           | ✅ PASS | Summarization call sends only conversation turns to the LLM (same data already in the system). No new secrets, PII, or external data paths introduced. MCP wiring uses existing least-privilege patterns. |
+| **Node.js + TypeScript**        | ✅ PASS | Two new TypeScript modules (`phaseSummarizer.ts`, `contextSummarizer.ts`), 5 new prompt markdown files. All follow existing patterns.                                                                     |
+| **MCP-first**                   | ✅ PASS | Design/Plan phases wired to use Context7 and Azure MCP via existing `McpManager`. No ad-hoc HTTP calls.                                                                                                   |
+| **Test-first (NON-NEGOTIABLE)** | ✅ PASS | Each FR group has a dedicated test file. Failing tests written before implementation. Zava assessment test serves as regression gate.                                                                     |
+| **CLI transparency**            | ✅ PASS | Summarization call uses existing spinner (`Thinking...`). Phase boundary prompt prevents confusing phase drift. Export includes all phases so users see full workshop output.                             |
+
+## Generated Artifacts
+
+| Artifact          | Path                                                                        | Description                                               |
+| ----------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Plan              | `specs/006-workshop-extraction-fixes/plan.md`                               | This file                                                 |
+| Research          | `specs/006-workshop-extraction-fixes/research.md`                           | 7 research topics with decisions, rationale, alternatives |
+| Data Model        | `specs/006-workshop-extraction-fixes/data-model.md`                         | 3 new entities, 0 schema changes, data flow diagram       |
+| Contracts         | `specs/006-workshop-extraction-fixes/contracts/summarization-and-export.md` | Summarization call interface + export fallback contract   |
+| Quickstart        | `specs/006-workshop-extraction-fixes/quickstart.md`                         | Development setup, file map, TDD workflow, verification   |
+| Quality Checklist | `specs/006-workshop-extraction-fixes/checklists/requirements.md`            | Bug traceability + cross-spec gap coverage                |

package/specs/006-workshop-extraction-fixes/quickstart.md

@@ -0,0 +1,101 @@
+# Quickstart: Workshop Phase Extraction & Tool Wiring Fixes
+
+**Feature**: 006-workshop-extraction-fixes  
+**Date**: 2026-03-04
+
+## Prerequisites
+
+- Node.js 22 LTS
+- GitHub Copilot CLI authenticated (`copilot auth login`)
+- `.env` with `FOUNDRY_PROJECT_ENDPOINT` + `FOUNDRY_MODEL_DEPLOYMENT_NAME` (for web search)
+- `.vscode/mcp.json` with MCP server configurations (for Context7, Azure, WorkIQ)
+
+## Development Setup
+
+```bash
+git checkout 006-workshop-extraction-fixes
+npm install
+npm run build
+```
+
+## Key Files to Modify
+
+### Phase 1: Lazy Web Search Config (BUG-001)
+
+```
+src/mcp/webSearch.ts          # isWebSearchConfigured() — already lazy, verify no caching
+src/cli/workshopCommand.ts    # Ensure loadEnvFile() called at entry point
+src/cli/developCommand.ts     # Same
+```
+
+### Phase 2: Phase Extraction Hardening (BUG-002)
+
+```
+src/loop/phaseSummarizer.ts   # NEW — post-phase summarization utility
+src/phases/phaseExtractors.ts # extractAllJsonBlocks(), extractJsonBlockForSchema()
+src/prompts/summarize/*.md    # NEW — per-phase summarization prompts (5 files)
+src/loop/conversationLoop.ts  # Hook phaseSummarize() after while loop
+```
+
+### Phase 3: Context Window Management (BUG-003)
+
+```
+src/phases/contextSummarizer.ts  # NEW — buildSummarizedContext(), renderSummarizedContext()
+src/phases/phaseHandlers.ts      # Replace ad-hoc context blocks with contextSummarizer
+src/loop/conversationLoop.ts     # Add infiniteSessions + phase boundary injection
+```
+
+### Phase 4: MCP Tool Wiring (BUG-005)
+
+```
+src/cli/workshopCommand.ts     # Create McpManager, WebSearchClient; pass to handlers
+src/phases/phaseHandlers.ts    # Extend PhaseHandlerConfig; Design/Plan accept MCP config
+```
+
+### Phase 5: Export Completeness (BUG-004)
+
+```
+src/sessions/exportWriter.ts   # Remove early-return guards, add conversation fallback
+```
+
+## Running Tests
+
+```bash
+# Unit tests (fast, ~10s)
+npm run test:unit
+
+# Integration tests (~15s)
+npm run test:integration
+
+# Live Zava assessment test (~13min, requires Copilot auth)
+npm run test:live -- tests/live/zavaFullWorkshop.spec.ts
+
+# Full suite
+npm test
+```
+
+## TDD Workflow (per phase)
+
+1. **Red**: Write failing tests in `tests/unit/` for the target FR group
+2. **Green**: Implement minimum code to pass
+3. **Review**: Run full suite (`npm test`), check `npm run typecheck` and `npm run lint`
+4. Repeat for next FR group
+
+## Verification
+
+After all changes, run the Zava assessment test:
+
+```bash
+npm run test:live -- tests/live/zavaFullWorkshop.spec.ts
+```
+
+Expected improvement: assessment score from 53% → 75%+ (SC-006).
+
+Key checks:
+
+- `session.ideas` populated after Ideate (was null)
+- `session.evaluation` populated after Design (was null)
+- `session.selection` populated after Select (was null + timeout)
+- `session.plan` populated after Plan (was null)
+- Export produces 6 markdown files (was 1)
+- Web search called during Discover (was skipped)

package/specs/006-workshop-extraction-fixes/research.md

@@ -0,0 +1,143 @@
+# Research: Workshop Phase Extraction & Tool Wiring Fixes
+
+**Feature**: 006-workshop-extraction-fixes  
+**Date**: 2026-03-04
+
+## Topic 1: Post-Phase Summarization LLM Call (FR-001–FR-007)
+
+### Decision: Dedicated summarization call with a new ConversationSession
+
+### Rationale
+
+The LLM produces rich conversational content but inconsistently includes structured JSON blocks matching the Zod schemas. Rather than building brittle prose parsers, a dedicated "one-shot" LLM call at phase end sends the full conversation transcript with explicit extraction instructions. This leverages the LLM's own ability to restructure its output.
+
+### Alternatives Considered
+
+1. **NLP-based prose extraction** — Rejected: fragile regex/heuristic parsers for markdown tables, bullet lists, and prose. High maintenance, low accuracy.
+2. **Instruct LLM to always output JSON inline** — Rejected: makes conversation unnatural, degrades facilitator UX, and the LLM still drifts.
+3. **Post-process each turn** — Current approach (already implemented). Retained as primary path; summarization is the fallback.
+
+### Implementation Details
+
+- **Insertion point**: After the `while` loop in `ConversationLoop.run()` (~line 193), before `return this.session`.
+- **Session strategy**: Create a **new** `ConversationSession` (not reuse the existing one) — avoids polluting conversation context and growing the already-long history. `CopilotClient.createSession()` is lightweight (SDK client is a singleton; only the session is new).
+- **Prompt structure**: Phase-specific system prompt with the exact Zod schema shape, plus the full phase transcript as the user message.
+- **Existing pattern**: Same as `ConversationLoop.streamResponse()` → `extractJsonBlock()` pipeline. Also mirrors the `postExtract` fire-once hook pattern from the Discover enricher.
+
+### Multi-Block Extraction (FR-007)
+
+- Current `extractJsonBlock()` uses non-global regexes → only finds first match.
+- New `extractAllJsonBlocks()` uses `/g` flag for fenced blocks and a bracket-depth counter for raw JSON.
+- New `extractJsonBlockForSchema<T>(response, schema)` tries each block with `safeParse()`, returns first valid match.
+
+---
+
+## Topic 2: Lazy Web Search Configuration (FR-008–FR-010)
+
+### Decision: `isWebSearchConfigured()` already checks `process.env` at call time — but `.env` must be loaded first
+
+### Rationale
+
+The function itself is stateless: `return Boolean(process.env.FOUNDRY_PROJECT_ENDPOINT && ...)`. The bug is **import ordering**: the test/CLI path may call it before `loadEnvFile()` runs. Fix: ensure `loadEnvFile()` is called at the top of `workshopCommand()` and `developCommand()` entry points.
+
+### Alternatives Considered
+
+1. **Cache the result lazily on first call** — Rejected: caching means if `.env` is loaded after the first check, the cached value is stale.
+2. **Module-level initialization** — Rejected: module load order is non-deterministic across import graphs.
+
+---
+
+## Topic 3: Context Window Management (FR-016–FR-019)
+
+### Decision: Deterministic `SummarizedPhaseContext` from structured session fields — no LLM call needed
+
+### Rationale
+
+Context summarization doesn't require an LLM call. Structured session fields (`businessContext`, `ideas`, `evaluation`, `selection`, `plan`) are already compact data. A `buildSummarizedContext()` function projects them into a ~200-line markdown block. This is deterministic, fast (<1ms), and testable.
+
+### Alternatives Considered
+
+1. **LLM summarization of prior turns** — Rejected for context building: adds latency (30s+), costs an API call per phase, and is non-deterministic.
+2. **Truncate raw turns** — Rejected: arbitrary truncation loses coherence.
+3. **SDK `infiniteSessions`** — Adopted as a supplementary measure, not the primary fix. Forward the same config used by Ralph Loop (`backgroundCompactionThreshold: 0.7`, `bufferExhaustionThreshold: 0.9`).
+
+### Current Problem
+
+Each phase handler builds ad-hoc context from only the immediately preceding phase's structured fields. If extraction failed, the next phase gets **no context at all**. The new `contextSummarizer.ts` replaces all ad-hoc context blocks with a unified, comprehensive summary that degrades gracefully when fields are null.
+
+---
+
+## Topic 4: MCP Tool Wiring in Workshop Flow (FR-011–FR-015)
+
+### Decision: Create McpManager + WebSearchClient in `workshopCommandInner()`, extend `PhaseHandlerConfig`
+
+### Rationale
+
+The `loadMcpConfig()` and `McpManager` infrastructure already exists (Feature 003). The gap is purely wiring: `workshopCommand.ts` never creates an McpManager. The Design and Plan handlers need an optional MCP config parameter passed through `PhaseHandlerConfig`.
+
+### Implementation Details
+
+- `McpManager` created from `.vscode/mcp.json` via existing `loadMcpConfig()`.
+- `WebSearchClient` created from Foundry env vars via `createWebSearchClient()` (already exists).
+- `PhaseHandlerConfig` extended with `mcpManager?: McpManager` and `webSearchClient?: WebSearchClient`.
+- Design handler: adds `postExtract` hook that queries Context7 for libraries referenced in `session.ideas`.
+- Plan handler: adds `postExtract` hook that queries Azure MCP for services referenced in `session.plan.architectureNotes`.
+- All calls wrap in try/catch for graceful degradation.
+
+---
+
+## Topic 5: Export Completeness (FR-020–FR-024)
+
+### Decision: Remove early `return null` guards, add conversation-turn fallback to all 5 phase generators
+
+### Rationale
+
+The Discover generator already has conversation-turn fallback code. The same pattern is applied to Ideate, Design, Select, Plan, and Develop generators: wrap structured rendering in an `if` guard, always include conversation turns if they exist.
+
+### Changes per generator
+
+| Generator | Current guard                                        | Change                                                     |
+| --------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| Ideate    | `if (!session.ideas?.length) return null`            | Remove; wrap idea rendering in `if`; add turn section      |
+| Design    | `if (!session.evaluation) return null`               | Remove; wrap eval rendering in `if`; add turn section      |
+| Select    | `if (!session.selection) return null`                | Remove; wrap selection rendering in `if`; add turn section |
+| Plan      | `if (!session.plan?.milestones?.length) return null` | Remove; wrap milestone rendering in `if`; add turn section |
+| Develop   | `if (!session.poc) return null`                      | Remove; wrap poc rendering in `if`; add turn section       |
+
+---
+
+## Topic 6: Phase Boundary Enforcement (FR-007b, FR-007c)
+
+### Decision: Inject boundary instruction in `ConversationLoop` system prompt builder
+
+### Rationale
+
+The LLM drifted between phases during the assessment (Ideate → Design, Plan → Develop). A system prompt instruction prevents this without changing phase prompts individually.
+
+### Implementation
+
+In `ConversationLoop.run()`, after building the system prompt, append:
+
+```
+You are in the {phase} phase. Do NOT introduce or transition to the next phase. The user will be offered a decision gate when this phase is complete.
+```
+
+---
+
+## Topic 7: Select Timeout Fallback (FR-019a)
+
+### Decision: Minimal-context retry, then user-directed selection
+
+### Rationale
+
+If context summarization (FR-016–018) doesn't prevent the Select timeout, a secondary fallback retries with only structured session fields (no conversation turns at all). If that also fails, the system presents the top-ranked idea from Design and asks the user to confirm manually.
+
+### Implementation
+
+In `ConversationLoop.run()`, wrap the initial `streamResponse()` in a try/catch. On timeout:
+
+1. Log the timeout.
+2. Create a new session with minimal context (just structured fields from `SummarizedPhaseContext`).
+3. Retry the initial message.
+4. If retry also fails, emit a user-facing message asking for manual selection:
+   "The AI could not process the selection. Based on the Design phase evaluation, the top-ranked idea is [X]. Would you like to confirm this selection? (y/N)"