sofia-cli 0.1.1

package/specs/005-ai-search-deploy/spec.md

@@ -0,0 +1,143 @@
+# Feature Specification: AI Foundry Search Service Deployment
+
+**Feature Branch**: `005-ai-search-deploy`  
+**Created**: 2026-03-01  
+**Status**: Draft  
+**Input**: User description: "Create the AI Foundry Search service as a bicep file and make it easily deployable using a script. This Search service will be the one used as a tool for web search, especially during the first step where we may need to search about the company, competitors and project specific information."
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 — One-Command Search Service Deployment (Priority: P1)
+
+A developer or workshop facilitator wants to provision the Azure AI Foundry infrastructure that powers sofIA's `web.search` tool. They run a single deployment script, provide a resource group name (and optionally an Azure subscription ID), and receive a fully deployed Foundry project with a web-search-enabled agent. The script writes the project endpoint URL and model deployment name to a `.env` file in the workspace root. Since the Foundry Agent Service uses the caller's Azure login credentials for authentication (no separate API key), and the sofIA CLI automatically loads the `.env` file at startup, the user has web search capabilities immediately — no manual environment variable configuration needed.
+
+**Why this priority**: Without the deployed Search service, the `web.search` tool has no backend. This is the foundational story — every other story depends on a working deployment.
+
+**Independent Test**: Can be tested by running the deployment script against an Azure subscription and verifying the Search service is provisioned, accessible, and returns valid responses to a test query.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user with an active Azure subscription and Owner/Contributor permissions, **When** they run the deployment script providing a resource group name (and optionally a subscription ID), **Then** all required Azure AI Foundry resources are provisioned, and the script writes the project endpoint URL and model deployment name to a `.env` file in the workspace root.
+2. **Given** the deployment script has completed successfully, **When** the user starts the sofIA CLI (which automatically loads the `.env` file) and is logged in to Azure, **Then** the sofIA CLI's `web.search` tool is enabled and returns search results with inline citations for a test query.
+3. **Given** a user provides an Azure region that does not support the required services, **When** they run the deployment script, **Then** the script fails with a clear error message explaining which services are unavailable in that region and suggests supported alternatives.
+
+---
+
+### User Story 2 — Infrastructure-as-Code Reproducibility (Priority: P2)
+
+A DevOps engineer or contributor wants to review, customize, and version-control the Azure infrastructure definition. They inspect the infrastructure template, understand the resources being created, modify parameters (such as region, naming conventions, or model selection), and deploy a customized version. The template is self-documenting with parameter descriptions and follows Azure best practices.
+
+**Why this priority**: Reproducibility and transparency are essential for team collaboration, auditing, and compliance. Without a readable, parameterized template, each deployment becomes a one-off manual effort.
+
+**Independent Test**: Can be tested by opening the infrastructure template files, verifying all parameters have descriptions and defaults, and deploying with customized parameter values.
+
+**Acceptance Scenarios**:
+
+1. **Given** a contributor opens the infrastructure template, **When** they review the file, **Then** every parameter has a description, a sensible default (where applicable), and the resources to be created are clearly documented.
+2. **Given** a user wants to deploy in a different Azure region, **When** they override the region parameter, **Then** the deployment succeeds in the new region (assuming service availability) without modifying the template itself.
+3. **Given** a user wants to use a different model for the Search agent, **When** they override the model deployment parameter, **Then** the deployment provisions the specified model instead of the default.
+
+---
+
+### User Story 3 — Seamless Integration with sofIA CLI (Priority: P3)
+
+After deployment, a workshop facilitator launches sofIA and begins the Discover phase (Step 1). When the AI asks about the user's business and industry, the facilitator expects sofIA to automatically use the web search tool to research the company, its competitors, and industry trends. The search results are grounded with citations and enrich the discovery conversation.
+
+**Why this priority**: This story validates the end-to-end value — deployment is only useful if the CLI can consume the service. However, the CLI integration layer already exists (the `web.search` tool in `webSearch.ts`); this story confirms it works with the newly deployed Foundry agent.
+
+**Independent Test**: Can be tested by deploying the service, configuring environment variables, starting a sofIA workshop session, and verifying that the Discover phase uses web search to retrieve real-time information about a named company.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Foundry Search agent is deployed and environment variables are configured, **When** a user starts a sofIA workshop and describes their business, **Then** the `web.search` tool is invoked to research the company and returns results with citations.
+2. **Given** the Foundry Search agent endpoint becomes temporarily unavailable, **When** the sofIA CLI tries to use the `web.search` tool, **Then** the CLI degrades gracefully (no crash) and the workshop continues without web search capabilities, with a warning to the user.
+
+---
+
+### User Story 4 — Teardown and Cost Management (Priority: P4)
+
+A user who has finished a workshop or testing session wants to remove all deployed Azure resources to avoid ongoing costs. They run a teardown command that cleanly removes the resource group and all contained resources.
+
+**Why this priority**: Azure resources incur costs when idle. Workshop and PoC scenarios are often short-lived, so easy teardown is important for cost management, though it doesn't block core functionality.
+
+**Independent Test**: Can be tested by deploying the infrastructure, running the teardown command, and verifying the resource group and all resources are deleted.
+
+**Acceptance Scenarios**:
+
+1. **Given** a previously deployed Foundry Search infrastructure, **When** the user runs the teardown command, **Then** the resource group and all contained resources are deleted within 10 minutes.
+2. **Given** the user runs the teardown command for a resource group that doesn't exist, **Then** the script exits with a clear informational message (not an error).
+
+---
+
+### Edge Cases
+
+- What happens when the user's Azure subscription has reached its quota for Cognitive Services resources?
+- How does the system handle a deployment where the specified resource group already contains a Foundry resource with the same name?
+- What happens if the user loses network connectivity mid-deployment?
+- How does the system handle Azure regions where the Foundry Agent Service or web search capability is not yet available?
+- What happens when the user's Azure account has insufficient permissions (e.g., Reader role instead of Owner/Contributor)?
+- How does the system handle concurrent deployments to the same resource group?
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: The project MUST include an infrastructure template that defines all Azure resources needed for the AI Foundry web search capability (Foundry account, project, model deployment, and agent capability).
+- **FR-002**: The project MUST include a deployment script that provisions the infrastructure with a single command, accepting the resource group as a required input and the Azure subscription as an optional input (defaults to the current az CLI subscription). If the specified resource group does not exist, the script MUST create it automatically.
+- **FR-003**: The deployment script MUST output the Foundry project endpoint URL and model deployment name needed to configure the sofIA CLI (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`), and MUST write them to a `.env` file in the workspace root (creating or updating the file as needed). Authentication uses the caller's Azure login credentials — no separate API key is needed.
+- **FR-004**: The infrastructure template MUST be parameterized, allowing users to customize the deployment name, region, and model selection without modifying the template. The default region MUST be `swedencentral`.
+- **FR-005**: The deployment script MUST validate prerequisites before attempting deployment (Azure CLI installed, user logged in, correct subscription selected, sufficient permissions).
+- **FR-006**: The deployment script MUST provide clear, actionable error messages when a deployment fails, including the specific failure reason and suggested remediation.
+- **FR-007**: The project MUST include a teardown command that removes all deployed resources by deleting the resource group.
+- **FR-008**: The infrastructure template MUST follow the basic agent setup pattern (Microsoft-managed resources) to minimize complexity and cost for workshop/PoC scenarios.
+- **FR-009**: The deployed agent MUST support the `web_search_preview` tool type to provide real-time web search grounded with citations.
+- **FR-010**: The deployment script MUST be executable from common development environments (Linux, macOS, Windows via WSL or Git Bash).
+- **FR-011**: The infrastructure template MUST include documentation (parameter descriptions, comments) explaining each resource and its purpose.
+- **FR-012**: The deployment MUST configure the Foundry agent with web search enabled and an appropriate model deployment for handling search queries. The default model deployment MUST be `gpt-4.1-mini`.
+- **FR-013**: The sofIA CLI MUST authenticate to the Foundry Agent Service using the user's Azure login credentials (e.g., via Azure Identity), eliminating the need for separate API key management.
+- **FR-014**: Search responses MUST include inline URL citations so the user can verify the sources of information surfaced during the workshop.
+- **FR-015**: The web search agent MUST follow an ephemeral lifecycle — created when a sofIA CLI session starts and automatically deleted when the session ends. The Bicep template provisions only the Foundry account, project, and model deployment; agent creation/deletion is handled at runtime by the CLI.
+- **FR-016**: If the CLI detects the legacy environment variables (`SOFIA_FOUNDRY_AGENT_ENDPOINT` or `SOFIA_FOUNDRY_AGENT_KEY`), it MUST display a clear error message instructing the user to migrate to the new variables (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`). The old variables MUST NOT be used for authentication.
+- **FR-017**: The sofIA CLI MUST load environment variables from a `.env` file in the project root at startup, without overwriting variables already present in `process.env`. If the `.env` file does not exist, the CLI MUST proceed normally without error.
+- **FR-018**: The deployment script MUST write the output environment variables (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`) to a `.env` file in the workspace root. If the file already exists, only the relevant entries MUST be updated; other entries MUST be preserved.
+
+### Key Entities
+
+- **Foundry Account**: The top-level Azure AI Foundry resource that hosts projects and model deployments. Identified by a unique name within a resource group.
+- **Foundry Project**: A project within the Foundry account where the web search agent operates. Provides the endpoint URL used by the sofIA CLI.
+- **Model Deployment**: A deployed language model (default: `gpt-4.1-mini`) within the Foundry account that processes search queries and generates grounded responses with citations.
+- **Web Search Agent**: A Foundry agent configured with the `web_search_preview` tool that performs real-time web searches. The agent is ephemeral — created when a sofIA CLI session starts and deleted when the session ends. No agent resource is managed in the Bicep template.
+- **Deployment Configuration**: The set of parameters (subscription, resource group, region, naming, model choice) that define a specific infrastructure deployment.
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: A new user can deploy the complete web search infrastructure in under 15 minutes, including prerequisite checks and resource provisioning.
+- **SC-002**: The deployment script succeeds on the first attempt for 95% of users who have a valid Azure subscription with Owner/Contributor permissions.
+- **SC-003**: After deployment, the sofIA CLI can perform a web search query and receive grounded results with citations within 10 seconds.
+- **SC-004**: Teardown removes all deployed resources and stops all associated billing within 10 minutes of execution.
+- **SC-005**: The infrastructure template is fully self-documented — a user can understand every resource and parameter by reading the template file alone, without external documentation.
+- **SC-006**: The deployment is reproducible — running the deployment script twice with the same parameters on different machines produces functionally equivalent environments.
+
+## Clarifications
+
+### Session 2026-03-01
+
+- Q: What should the default Azure region be for the deployment template? → A: `swedencentral`
+- Q: What should the default model deployment for the web search agent be? → A: `gpt-4.1-mini`
+- Q: Should the Foundry agent be persistent or ephemeral? → A: Ephemeral per CLI session (created on session start, deleted on session end)
+- Q: Should the deployment script auto-create the resource group if it doesn't exist? → A: Yes, auto-create it (subscription-level deployment)
+- Q: Should the CLI support both old and new env vars during migration? → A: Clean break — only new env vars, with error message if old ones detected
+
+## Assumptions
+
+- Users have an active Azure subscription with Owner or Contributor permissions on the target resource group.
+- The Azure CLI is installed and the user is already authenticated (`az login`). This same Azure login is used for both deploying the infrastructure and authenticating the sofIA CLI to the Foundry Agent Service at runtime.
+- The target Azure region supports Azure AI Foundry and the Grounding with Bing Search capability (uses Bing Search behind the scenes — governed by [Grounding with Bing terms of use](https://www.microsoft.com/bing/apis/grounding-legal-enterprise)).
+- The basic agent setup (Microsoft-managed infrastructure) is sufficient for workshop and PoC use cases — standard agent setup with BYO resources is out of scope for this feature.
+- The sofIA CLI's existing `webSearch.ts` module uses raw HTTP POST with a bearer token (`SOFIA_FOUNDRY_AGENT_ENDPOINT` + `SOFIA_FOUNDRY_AGENT_KEY`). This feature will migrate the web search integration to the Foundry Agent Service SDK pattern, which authenticates via Azure Identity credentials and uses the `web_search_preview` tool type. The environment variables will change from `SOFIA_FOUNDRY_AGENT_ENDPOINT`/`SOFIA_FOUNDRY_AGENT_KEY` to `FOUNDRY_PROJECT_ENDPOINT`/`FOUNDRY_MODEL_DEPLOYMENT_NAME`. This is a clean break — old env vars will trigger an error message guiding migration; they will not be silently ignored or used as fallback.
+- The Foundry web search agent returns responses with inline URL citations (annotations of type `url_citation`), which the sofIA CLI should surface to the user.
+- Cost for Grounding with Bing Search is usage-based and acceptable for workshop scenarios (typically a small number of queries per session). See [pricing](https://www.microsoft.com/bing/apis/grounding-pricing).
+- The infrastructure files will live in a new `infra/` directory at the project root, following Azure conventions.
+- An Azure admin may need to ensure web search is not disabled at the subscription level (see `az feature unregister --name OpenAI.BlockedTools.web_search --namespace Microsoft.CognitiveServices`).

package/specs/005-ai-search-deploy/tasks.md

@@ -0,0 +1,284 @@
+# Tasks: AI Foundry Search Service Deployment
+
+**Input**: Design documents from `/specs/005-ai-search-deploy/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/web-search-tool.md, quickstart.md
+
+**Tests**: Tests are REQUIRED for new behavior in this repository (Red → Green → Review). Include test tasks for each user story and write them first.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3, US4)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Infrastructure**: `infra/` at repository root
+- **Source code**: `src/` at repository root
+- **Tests**: `tests/unit/`, `tests/integration/` at repository root
+- **Documentation**: `docs/` at repository root
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Install new dependencies, create directory structure, establish foundational config
+
+- [x] T001 Install `@azure/ai-projects@beta` and `@azure/identity` as production dependencies in package.json
+- [x] T002 [P] Create `infra/` directory structure with placeholder files: `infra/main.bicep`, `infra/main.bicepparam`, `infra/deploy.sh`, `infra/teardown.sh`
+- [x] T003 [P] Add TypeScript ambient module declarations for `@azure/ai-projects` and `@azure/identity` if needed in src/types/
+
+**Checkpoint**: Dependencies installed, directory structure ready, `npm run typecheck` passes
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core changes that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T004 Update `isWebSearchConfigured()` in src/mcp/webSearch.ts to check new env vars (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`) instead of legacy vars
+- [x] T005 [P] Add legacy env var detection to preflight checks in src/cli/preflight.ts — fail with migration error message if `SOFIA_FOUNDRY_AGENT_ENDPOINT` or `SOFIA_FOUNDRY_AGENT_KEY` are set (FR-016)
+- [x] T006 [P] Update docs/environment.md — replace legacy env var documentation with new `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME` vars, document `DefaultAzureCredential` auth model
+
+**Checkpoint**: Foundation ready — legacy env vars rejected, new env var pattern established, `npm run typecheck` and `npm run lint` pass
+
+---
+
+## Phase 3: User Story 1 — One-Command Search Service Deployment (Priority: P1) 🎯 MVP
+
+**Goal**: A developer runs `./infra/deploy.sh` with subscription + resource group and gets a fully deployed Foundry project with web-search-enabled agent infrastructure. Script outputs configuration values.
+
+**Independent Test**: Run the deployment script against an Azure subscription and verify all 5 resources are provisioned, script outputs correct env var values.
+
+**FR Coverage**: FR-001, FR-002, FR-003, FR-005, FR-006, FR-008, FR-009, FR-010, FR-012
+
+### Tests for User Story 1 (REQUIRED) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [x] T007 [P] [US1] Unit test for deploy script prerequisite validation (az CLI check, login check) in tests/unit/infraDeploy.spec.ts — test parameter parsing, missing required args, default values
+- [x] T008 [P] [US1] Unit test verifying Bicep template structure (validate JSON compilation output has all 5 expected resource types) in tests/unit/infraBicep.spec.ts
+
+### Implementation for User Story 1
+
+- [x] T009 [US1] Create Bicep template `infra/main.bicep` with all 5 resources: `Microsoft.CognitiveServices/accounts` (kind: AIServices, allowProjectManagement: true, customSubDomainName), `accounts/deployments` (gpt-4.1-mini, GlobalStandard), `accounts/projects`, `accounts/capabilityHosts` (Agents), `accounts/projects/capabilityHosts` (Agents). Use `targetScope = 'subscription'` with resource group creation per research.md R1
+- [x] T010 [US1] Create Bicep parameter file `infra/main.bicepparam` with defaults: location=swedencentral, modelDeploymentName=gpt-4.1-mini, modelName=gpt-4.1-mini, modelVersion=2025-04-14, modelSkuName=GlobalStandard per data-model.md FoundryDeploymentConfig
+- [x] T011 [US1] Implement deployment script `infra/deploy.sh` — parse CLI flags (--subscription, --resource-group, --location, --account-name, --model), validate prerequisites (az CLI installed, user logged in, subscription accessible), run `az deployment sub create`, query Bicep outputs (projectEndpoint, modelDeploymentName), write env vars to `.env` file per contracts/web-search-tool.md deploy.sh contract
+- [x] T012 [US1] Make `infra/deploy.sh` executable (chmod +x) and add shebang `#!/usr/bin/env bash`, set error handling (`set -euo pipefail`), add clear error messages with exit codes (0=success, 1=prereq fail, 2=deploy fail) per FR-006 and contracts
+
+**Checkpoint**: User Story 1 complete — `./infra/deploy.sh -g <rg>` provisions all resources and writes env vars to `.env`. Tests in T007/T008 pass.
+
+---
+
+## Phase 4: User Story 2 — Infrastructure-as-Code Reproducibility (Priority: P2)
+
+**Goal**: Every Bicep parameter has a description and sensible default. Users can customize region, model, and naming without modifying the template. Template is self-documenting.
+
+**Independent Test**: Open `infra/main.bicep`, verify every `@description()` decorator is present. Deploy with `--location eastus --model gpt-4o-mini` and verify it succeeds with those overrides.
+
+**FR Coverage**: FR-004, FR-011
+
+### Tests for User Story 2 (REQUIRED) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [x] T013 [P] [US2] Unit test verifying all Bicep parameters have `@description()` decorators in tests/unit/infraBicep.spec.ts — parse main.bicep and confirm every `param` has a preceding `@description` annotation
+- [x] T014 [P] [US2] Unit test verifying Bicep parameters have defaults where specified in data-model.md FoundryDeploymentConfig — location defaults to swedencentral, model to gpt-4.1-mini
+
+### Implementation for User Story 2
+
+- [x] T015 [US2] Add `@description()` decorators to all Bicep parameters in infra/main.bicep — location, accountName, projectName, modelDeploymentName, modelName, modelVersion, modelSkuName, modelSkuCapacity, resourceGroupName per FR-011
+- [x] T016 [US2] Add inline comments to each Bicep resource in infra/main.bicep explaining its purpose (Foundry account, model deployment, project, account capability host, project capability host) per FR-011 and SC-005
+- [x] T017 [US2] Ensure deploy.sh passes parameter overrides through to Bicep deployment — `--location`, `--account-name`, and `--model` flags map to Bicep parameter overrides via `az deployment sub create --parameters` per FR-004
+
+**Checkpoint**: User Story 2 complete — template is self-documenting (SC-005), customizable region/model/naming (FR-004) works via CLI flag overrides. Tests in T013/T014 pass.
+
+---
+
+## Phase 5: User Story 3 — Seamless Integration with sofIA CLI (Priority: P3)
+
+**Goal**: The sofIA CLI's `web.search` tool uses `@azure/ai-projects` SDK with `DefaultAzureCredential` auth (no API key). Ephemeral agent created lazily on first search call, deleted on session end. Search responses include URL citations. Graceful degradation on failure.
+
+**Independent Test**: Set `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME`, start a sofIA workshop, describe a company — web search returns grounded results with citations. Unset env vars — workshop proceeds without web search, no crash.
+
+**FR Coverage**: FR-013, FR-014, FR-015, FR-016
+
+### Tests for User Story 3 (REQUIRED) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [x] T018 [P] [US3] Unit test for updated `WebSearchConfig` validation (projectEndpoint format, modelDeploymentName non-empty) in tests/unit/webSearch.spec.ts per data-model.md validation rules
+- [x] T019 [P] [US3] Unit test for legacy env var detection — `isWebSearchConfigured()` returns false when only old vars set, returns true when new vars set in tests/unit/webSearch.spec.ts
+- [x] T020 [P] [US3] Unit test for `createWebSearchTool()` graceful degradation — returns `{ results: [], degraded: true, error }` when credential fails, agent creation fails, or network error in tests/unit/webSearch.spec.ts per contracts/web-search-tool.md degradation scenarios
+- [x] T021 [P] [US3] Unit test for citation extraction — parses `url_citation` annotations from Foundry response into `WebSearchResultItem[]` with title, url, snippet and deduplicates sources in tests/unit/webSearch.spec.ts per contracts/web-search-tool.md output format
+- [x] T022 [P] [US3] Integration test for ephemeral agent lifecycle (create → query → cleanup) using faked `AIProjectClient` in tests/integration/webSearchAgent.spec.ts — verify agent created on first call, reused on second call, deleted on `destroyWebSearchSession()` per data-model.md AgentSession state transitions
+- [x] T023 [P] [US3] Unit test for preflight legacy env var check — verify preflight fails with clear migration message when `SOFIA_FOUNDRY_AGENT_ENDPOINT` or `SOFIA_FOUNDRY_AGENT_KEY` are set in tests/unit/preflight.spec.ts per data-model.md LegacyEnvVarError
+
+### Implementation for User Story 3
+
+- [x] T024 [US3] Update `WebSearchConfig` interface in src/mcp/webSearch.ts — replace `endpoint`/`apiKey`/`fetchFn` with `projectEndpoint`/`modelDeploymentName` per data-model.md entity 3
+- [x] T025 [US3] Implement `AgentSession` class in src/mcp/webSearch.ts — lazy initialization with `AIProjectClient` + `DefaultAzureCredential`, `agents.createVersion()` for web_search_preview agent, conversation creation, state tracking (uninitialized → initialized → cleaned up) per data-model.md entity 4 and research.md R4/R8
+- [x] T026 [US3] Implement citation extraction in src/mcp/webSearch.ts — parse `response.output` for `url_citation` annotations, map to `WebSearchResultItem[]` (title, url, snippet), deduplicate into `sources[]` per contracts/web-search-tool.md output format and FR-014
+- [x] T027 [US3] Rewrite `createWebSearchTool()` in src/mcp/webSearch.ts — replace raw HTTP POST with `AgentSession.initialize()` on first call, `openAIClient.responses.create()` for queries, return structured `WebSearchResult` with citations. Handle all degradation scenarios per contracts/web-search-tool.md degradation table
+- [x] T028 [US3] Implement `destroyWebSearchSession()` in src/mcp/webSearch.ts — delete conversation and agent version, register `process.on('beforeExit', ...)` handler, log warnings on cleanup failure (no throw) per research.md R8 lifecycle contract
+- [x] T029 [US3] Update `isWebSearchConfigured()` in src/mcp/webSearch.ts — check `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME` (not legacy vars)
+- [x] T030 [US3] Wire `destroyWebSearchSession()` cleanup into workshop session teardown in src/cli/workshopCommand.ts — call on workshop exit/completion to ensure ephemeral agent is deleted per FR-015
+- [x] T031 [US3] Update src/develop/mcpContextEnricher.ts — ensure `isWebSearchConfigured()` import path is correct and behavior aligns with new env var check
+
+**Checkpoint**: User Story 3 complete — sofIA CLI uses Foundry Agent Service SDK for web search, ephemeral agent lifecycle works, citations displayed, graceful degradation on failure. All tests in T018-T023 pass. `npm run typecheck` and `npm run lint` pass.
+
+---
+
+## Phase 6: User Story 4 — Teardown and Cost Management (Priority: P4)
+
+**Goal**: User runs `./infra/teardown.sh --resource-group <name>` to delete all deployed resources. Clean exit when resource group doesn't exist.
+
+**Independent Test**: Deploy infrastructure, run teardown, verify resource group deleted. Run teardown on non-existent group — clean informational message, exit 0.
+
+**FR Coverage**: FR-007
+
+### Tests for User Story 4 (REQUIRED) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [x] T032 [P] [US4] Unit test for teardown script parameter validation — required --resource-group flag, exit code 0 when group not found, exit code 1 on prereq failure in tests/unit/infraTeardown.spec.ts per contracts/web-search-tool.md teardown.sh contract
+
+### Implementation for User Story 4
+
+- [x] T033 [US4] Implement teardown script `infra/teardown.sh` — parse --resource-group flag, check az CLI prerequisites, verify resource group exists (informational exit 0 if not), prompt for confirmation (unless --yes), execute `az group delete --yes --no-wait`, print confirmation per contracts/web-search-tool.md teardown.sh contract
+- [x] T034 [US4] Make `infra/teardown.sh` executable (chmod +x) and add shebang, set `set -euo pipefail`, handle exit codes (0=success/not-found, 1=prereq fail, 2=deletion fail)
+
+**Checkpoint**: User Story 4 complete — teardown script deletes resource group cleanly, handles non-existent groups gracefully. Test in T032 passes.
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+**Purpose**: Documentation, validation, cleanup across all stories
+
+- [x] T035 [P] Update README.md — add "Web Search Setup" section with link to quickstart.md and brief deployment instructions
+- [x] T036 [P] Verify quickstart.md end-to-end flow matches final implementation — deploy → configure → verify → teardown in specs/005-ai-search-deploy/quickstart.md
+- [x] T037 Run `npm run typecheck` and fix any remaining TypeScript errors across all modified files
+- [x] T038 Run `npm run lint` and fix any ESLint `import/order` warnings across all modified files
+- [x] T039 Run full test suite (`npm test`) and ensure no regressions in existing tests
+- [x] T040 [P] Install `dotenv` as a production dependency and create `src/cli/envLoader.ts` — load `.env` file at startup without overwriting existing env vars (FR-017)
+- [x] T041 [P] Wire `loadEnvFile()` call into `src/cli/index.ts` before CLI setup (FR-017)
+- [x] T042 [P] Create unit tests for envLoader in `tests/unit/cli/envLoader.spec.ts` — test loading, no-overwrite, and missing file scenarios
+- [x] T043 [P] Update `infra/deploy.sh` to write `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME` to `.env` file in workspace root (FR-018)
+- [x] T044 Make `--subscription` flag optional in `infra/deploy.sh` — defaults to current az CLI subscription
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies — start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion — BLOCKS all user stories
+- **US1 (Phase 3)**: Depends on Foundational — creates Bicep + deploy script
+- **US2 (Phase 4)**: Depends on US1 (enhances the same Bicep template + deploy script created in US1)
+- **US3 (Phase 5)**: Depends on Foundational — independent of US1/US2 (uses fakes for testing; only needs real deployment for live validation)
+- **US4 (Phase 6)**: Depends on Foundational — independent of US1-US3
+- **Polish (Phase 7)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) — No dependencies on other stories
+- **User Story 2 (P2)**: Depends on US1 (enhances the Bicep template and deploy script created in US1)
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) — Independent of US1/US2 (uses faked SDK clients for tests)
+- **User Story 4 (P4)**: Can start after Foundational (Phase 2) — Independent of US1-US3
+
+### Within Each User Story
+
+- Tests MUST be written and FAIL before implementation
+- Models/interfaces before services
+- Services before integration
+- Core implementation before edge-case handling
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- T002 and T003 can run in parallel (Phase 1 setup)
+- T004, T005, T006 can run in parallel (Phase 2 foundational — different files)
+- T007 and T008 can run in parallel (US1 tests — different test files)
+- **US1 and US3 can run in parallel** after Foundational (different file sets: infra/ vs src/mcp/)
+- **US1 and US4 can run in parallel** after Foundational (deploy.sh vs teardown.sh)
+- **US3 and US4 can run in parallel** after Foundational (src/ vs infra/)
+- All US3 tests (T018-T023) can run in parallel (different test files or independent test cases)
+- T035 and T036 can run in parallel (different docs)
+
+---
+
+## Parallel Example: User Story 3
+
+```bash
+# Launch all tests for US3 together (6 parallel test tasks):
+T018: Unit test for WebSearchConfig validation in tests/unit/webSearch.spec.ts
+T019: Unit test for legacy env var detection in tests/unit/webSearch.spec.ts
+T020: Unit test for graceful degradation in tests/unit/webSearch.spec.ts
+T021: Unit test for citation extraction in tests/unit/webSearch.spec.ts
+T022: Integration test for agent lifecycle in tests/integration/webSearchAgent.spec.ts
+T023: Unit test for preflight legacy check in tests/unit/preflight.spec.ts
+
+# After tests fail (Red), implement in order:
+T024: Update WebSearchConfig interface
+T025: Implement AgentSession class
+T026: Implement citation extraction
+T027: Rewrite createWebSearchTool()
+T028: Implement destroyWebSearchSession()
+T029: Update isWebSearchConfigured()
+T030: Wire cleanup into workshop session
+T031: Update mcpContextEnricher import
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup (T001-T003)
+2. Complete Phase 2: Foundational (T004-T006)
+3. Complete Phase 3: User Story 1 (T007-T012)
+4. **STOP and VALIDATE**: Deploy to Azure, verify all 5 resources created, env var output correct
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Setup + Foundational → Foundation ready (new deps, env var migration)
+2. Add US1 → Test deploy script → Deploy to Azure (MVP — infrastructure works!)
+3. Add US2 → Verify template quality (parameterization, documentation)
+4. Add US3 → Test CLI integration → Workshop uses web search with citations
+5. Add US4 → Test teardown → Full lifecycle (deploy → use → teardown)
+6. Polish → Docs, lint, typecheck, full suite
+
+### Parallel Team Strategy
+
+With multiple developers after Foundational phase:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: US1 (deploy) then US2 (template quality)
+   - Developer B: US3 (CLI integration — largest story, 14 tasks)
+   - Developer C: US4 (teardown — smallest, 3 tasks)
+3. All merge and Polish together
+
+---
+
+## Notes
+
+- Total tasks: **44**
+- US1: 6 tasks (2 test + 4 impl)
+- US2: 5 tasks (2 test + 3 impl)
+- US3: 14 tasks (6 test + 8 impl) — largest story, core SDK migration
+- US4: 3 tasks (1 test + 2 impl) — smallest story
+- Setup: 3 tasks
+- Foundational: 3 tasks
+- Polish: 10 tasks (includes dotenv integration T040-T042, .env writing T043, subscription-optional T044)
+- Parallel opportunities: US1 ‖ US3 ‖ US4 after Foundational; numerous within-story [P] tasks
+- MVP: US1 alone delivers deployable infrastructure (12 tasks through Phase 3)
+- Each story is independently testable per spec acceptance scenarios

package/specs/006-workshop-extraction-fixes/checklists/requirements.md

@@ -0,0 +1,61 @@
+# Specification Quality Checklist: Workshop Phase Extraction & Tool Wiring Fixes
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-03-04  
+**Feature**: [specs/006-workshop-extraction-fixes/spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Bug Traceability
+
+- [x] Each bug from the assessment is mapped to at least one FR
+- [x] BUG-001 (lazy web search config) → FR-008, FR-009, FR-010
+- [x] BUG-002 (extraction failures) → FR-001 through FR-007, FR-007a
+- [x] BUG-003 (context window timeout) → FR-016 through FR-019, FR-019a
+- [x] BUG-004 (export incompleteness) → FR-020 through FR-024
+- [x] BUG-005 (MCP tools not wired) → FR-011 through FR-015, FR-012a
+- [x] Each bug maps to at least one success criterion
+- [x] Assessment source linked (Zava Industries assessment results)
+
+## Cross-Spec Gap Coverage
+
+- [x] GAP-A (LLM phase drift) → FR-007b, FR-007c (phase boundary enforcement)
+- [x] GAP-C (WorkIQ explicit wiring) → FR-012a (WorkIQ consent and enrichment storage)
+- [x] GAP-D (enrichment downstream use) → FR-017 (explicitly lists discoveryEnrichment)
+- [x] GAP-E (Mermaid architecture diagrams) → FR-007a (Design summarization includes Mermaid)
+- [x] GAP-G (Select timeout fallback after summarization) → FR-019a (minimal-context retry + user fallback)
+- [x] GAP-B (input-counting test harness) → Noted in Edge Cases as test infrastructure concern
+- [x] GAP-F (cards dataset fidelity) → Out of scope (prompt tuning, not extraction/wiring)
+- [x] GAP-H (search results UX) → Already covered by spec 001 FR-043a/FR-043b
+
+## Notes
+
+- Spec was generated directly from the Zava Industries full-session assessment (tests/e2e/zava-assessment/results/assessment-results.md)
+- All 5 bugs scored and prioritized by severity
+- 29 functional requirements across 6 categories (original 24 + 5 gap additions: FR-007a, FR-007b, FR-007c, FR-012a, FR-019a)
+- 6 measurable success criteria including the meta-criterion SC-006 (Zava assessment score improvement from 53% to 75%+)
+- Cross-referenced against specs 001, 003, 005 and the `003-next-spec-gaps.md` gap tracker
+- Out of scope section explicitly defers prose-based NLP extraction, retry logic, template selection, PTY testing, and cards dataset fidelity

package/specs/006-workshop-extraction-fixes/contracts/summarization-and-export.md

@@ -0,0 +1,131 @@
+# Contract: Post-Phase Summarization Call
+
+**Feature**: 006-workshop-extraction-fixes  
+**FRs**: FR-001 through FR-007
+
+## Purpose
+
+After each phase's conversation loop completes, if the expected structured session field is still `null`, make a one-shot LLM call to extract structured data from the full conversation transcript.
+
+## Interface
+
+### Input
+
+```
+phaseSummarize(
+  client: CopilotClient,
+  phase: PhaseValue,
+  session: WorkshopSession,
+  handler: PhaseHandler
+): Promise<Partial<WorkshopSession>>
+```
+
+### Behavior
+
+1. Check if the relevant session field for `phase` is still null:
+   - Ideate: `session.ideas`
+   - Design: `session.evaluation`
+   - Select: `session.selection`
+   - Plan: `session.plan`
+   - Develop: `session.poc`
+   - Discover: `session.businessContext` (unlikely to be null, but included for completeness)
+
+2. If the field is already populated, return `{}` (no-op).
+
+3. Build the phase transcript from `session.turns` filtered by `t.phase === phase`.
+
+4. Create a new `ConversationSession` with a phase-specific summarization system prompt loaded from `src/prompts/summarize/{phase}-summary.md`.
+
+5. Send the transcript as a single user message. Collect the full response.
+
+6. Run `handler.extractResult(session, response)` on the summarization response.
+
+7. Return the extracted updates (may be `{}` if extraction still fails).
+
+### Error Handling
+
+- If `client.createSession()` or `send()` throws, log a warning and return `{}`.
+- If the response doesn't contain valid JSON matching the schema, log a warning and return `{}`.
+- Never throw — the summarization call is a best-effort fallback.
+
+### Summarization Prompt Shape (per phase)
+
+Each prompt in `src/prompts/summarize/{phase}-summary.md` MUST include:
+
+1. A role instruction: "You are a data extraction assistant."
+2. The exact JSON schema shape expected (with field names, types, and constraints).
+3. An instruction to output ONLY a fenced JSON code block.
+4. For Design phase: additionally request a Mermaid architecture diagram (FR-007a).
+
+---
+
+# Contract: Export Writer Conversation Fallback
+
+**Feature**: 006-workshop-extraction-fixes  
+**FRs**: FR-020 through FR-024
+
+## Purpose
+
+Export Markdown files for all phases that had conversation data, even if structured session fields are null.
+
+## Interface
+
+Each `generate{Phase}Markdown(session: WorkshopSession): string | null` function follows this contract:
+
+### Output Structure (when both structured data and turns exist)
+
+```markdown
+# {Phase} Phase
+
+## {Structured Section — phase-specific}
+
+{Rendered from session field if non-null}
+
+## Conversation
+
+**user**: {turn content}
+
+**assistant**: {turn content}
+...
+```
+
+### Output Structure (when only turns exist)
+
+```markdown
+# {Phase} Phase
+
+## Conversation
+
+**user**: {turn content}
+
+**assistant**: {turn content}
+...
+```
+
+### Returns `null` Only When
+
+- No structured data AND no conversation turns exist for the phase.
+
+### `summary.json` Enhancement
+
+```json
+{
+  "files": [
+    { "path": "discover.md", "type": "markdown" },
+    { "path": "ideate.md", "type": "markdown" },
+    { "path": "design.md", "type": "markdown" },
+    { "path": "select.md", "type": "markdown" },
+    { "path": "plan.md", "type": "markdown" },
+    { "path": "develop.md", "type": "markdown" }
+  ],
+  "highlights": [
+    "Business: {from businessContext}",
+    "Ideas: {count} ideas generated",
+    "Selection: {ideaId or 'pending'}",
+    "Plan: {milestone count} milestones",
+    ...
+  ]
+}
+```
+
+Highlights include at least one entry per phase with turns, even if the structured field is null. Fallback highlights use the first assistant turn's opening sentence (truncated to 100 chars).