sofia-cli 0.1.1

package/.github/copilot-instructions.md

@@ -0,0 +1,257 @@
+# sofIA - Copilot Instructions
+
+sofIA is an agentic system built with the **GitHub Copilot SDK** that implements the AI Discovery Cards workshop process. It guides users through discovering, ideating, designing, planning, and developing AI solutions for business needs.
+
+## Project Overview
+
+This project reimagines [Microsoft's AI Discovery Agent (AIDA)](https://github.com/microsoft/ai-discovery-agent/) using the GitHub Copilot SDK (`@github/copilot-sdk`) instead of Python/LangGraph. It extends AIDA's workshop facilitation by adding:
+
+1. **Idea Selection** - Automatically selects the most feasible AI use case from generated ideas
+2. **Planning** - Creates implementation plans for the selected idea
+3. **PoC Development** - Generates working proof-of-concept code to demonstrate the idea
+4. **Discovery Cards** - from [AI Discovery Cards Agent](https://github.com/microsoft-partner-solutions-ai/agent-guides/tree/main/ai-discovery-cards-agent)
+
+## Architecture
+
+### Agent Flow
+```
+User Input → Discovery Agent → Ideation Agent → Design Agent → Selection Agent → Planning Agent → Development Agent
+```
+
+Examples for these agents can be found in the [src/originalPrompts/](../src/originalPrompts/) directory.
+
+### Core Components
+
+- **Copilot Enabled App** - Main entry point handling GitHub Copilot chat interactions via `@github/copilot-sdk`
+- **MCP Integrations** - External services for gathering context and generating solutions:
+  - **WorkIQ** - Process analysis and task discovery
+  - **Context7** - Documentation and context retrieval  
+  - **Microsoft Learn** - Azure/AI documentation
+  - **GitHub MCP** - Repository search, code examples, and issue tracking
+
+### AI Discovery Workshop Process
+
+The system implements the 12 step AI Discovery Cards methodology, and after this it goes beyond by selecting the best idea, creating a plan, and generating PoC code:
+
+### Phase 1: AI discovery and ideation
+
+For each step:
+
+- Ask for required input.
+- Summarize or reflect back what was shared.
+- Propose moving to the next step only when ready.
+
+#### Step 1: Understand the Business
+
+- Ask for a description of the business and its challenges.
+- Store this information for later use.
+
+#### Step 2: Choose a Topic
+
+- Identify areas to work on.
+- Prioritize and define today’s focus.
+
+#### Step 3: Ideate Activities
+
+- Brainstorm key activities in the focus area.
+- Identify what’s not being done due to difficulty.
+
+#### Step 4: Map Workflow
+
+- Visualize the activity flow.
+- Vote on critical steps based on business and human value.
+- Identify key metrics (e.g., hours/week, NSAT).
+
+#### Step 5: Explore AI Envisioning Cards
+
+- Ask the AI Discovery Expert to present cards to attendees.
+
+#### Step 6: Score Cards
+
+- Ask which cards were selected and how they were scored.
+
+#### Step 7: Review Top Cards
+
+- Select up to 15 cards.
+- Aggregate similar ones.
+
+#### Step 8: Map Cards to Workflow
+
+- Align cards to workflow steps.
+- Ensure key metrics are clear.
+
+#### Step 9: Generate Ideas
+
+- Ask the Design Thinking Expert to help ideate for each step.
+
+### Step 10: Create Idea Cards
+
+For each idea, capture:
+
+- **Title**
+- **Description**
+- **Workflow Steps Covered**
+- **Aspirational Solution Scope**
+
+#### Step 11: Evaluate Ideas
+
+- Use a feasibility/value matrix.
+- Consider KPIs and metrics.
+
+#### Step 12: Assess Impact
+
+For each idea, evaluate:
+
+- Data needed
+- Risks
+- Business impact
+- Human value
+- Key metrics influenced
+
+### Phase 2: Idea Selection
+
+After generating and evaluating ideas, the system will automatically select the most promising one based on feasibility, business impact, and human value. This selection will be made transparent to the user, with an explanation of why it was chosen, and will let the user confirm or override the selection before proceeding to planning and development.
+
+### Phase 3: Planning and PoC Development
+
+Once an idea is selected, the system will create a high-level implementation plan, breaking down the idea into actionable steps. It will then generate proof-of-concept code to demonstrate the core functionality of the idea, using best practices for modularity and maintainability. The generated code will be designed to be easily extendable for full implementation after the workshop.
+
+This code will be generated by a [Ralph Loop](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop) agent that iteratively refines the implementation until the PoC meets the defined functionality, then stops. The system will also provide guidance on next steps for full implementation after the workshop concludes.
+
+## Tech Stack
+
+- **Runtime**: Node.js / TypeScript
+- **SDK**: `@github/copilot-sdk`
+- **MCP Protocol**: Model Context Protocol for tool integrations
+- **Deployment**: GitHub App (Copilot SDK enabled App)
+
+> **Note**: This repository currently contains specifications, workshop prompts, and
+> governance/templates (under `.specify/`). If/when implementation code is added,
+> it must follow the constitution and the stack expectations above.
+
+## Development Commands (when implementation code exists)
+
+If this repo contains a `package.json`, prefer the scripts defined there
+(`npm test`, `npm run lint`, etc.). Do not invent commands that do not exist.
+
+## Key Conventions
+
+### All Changes — Test-Driven Development (TDD) + Lint/Typecheck Loop
+
+All new behavior and bug fixes **must** follow a TDD workflow (Red → Green → Lint → Review).
+Do not modify production code until a failing test proves the change is needed.
+**Code must never be committed if `npm run lint` or `npm run typecheck` report errors.**
+
+1. **Reproduce** — Identify the root cause and the exact code path that fails.
+2. **Write a failing test first** — Create a test (unit or integration) that exercises the buggy behaviour and fails on the current code. The test name should describe the symptom (e.g., `"captures LLM text after tool-calling loop"`).
+3. **Run the test** — Confirm it fails for the expected reason (`npm test -- <test-file>`).
+4. **Fix the production code** — Make the minimal change needed to make the test pass.
+5. **Run lint + typecheck** — `npm run lint && npm run typecheck` must both pass. Fix any errors before continuing.
+6. **Run the test again** — Confirm it passes after the lint/typecheck fixes.
+7. **Run the full suite** — Ensure the full test suite remains green (no regressions).
+8. **Run lint + typecheck one final time** — Confirm both still pass after the full suite run. **Do not commit until they do.**
+
+> **Loop invariant:** After every code change — no matter how small — run `npm run lint && npm run typecheck` before moving on. Treat a lint or typecheck failure the same as a failing test: stop, fix, re-run.
+
+**Test placement guidelines (when a test suite exists):**
+| Scope | Directory | When to use |
+|-------|-----------|-------------|
+| Unit | `tests/unit/` | Pure-function logic, renderers, models, single-module behaviour |
+| Integration | `tests/integration/` | Multi-module flows, CLI subprocess, conversation loops |
+| Contract | `tests/contract/` | CLI command shapes, error formats, public API surface |
+
+**If tests do not exist yet:** The first implementation work for a feature must include setting up a minimal test runner and a first failing test, then proceed with implementation.
+
+**Mock boundaries:** Mock at the module boundary (e.g., Vitest `vi.mock()`), not inside functions. For Copilot SDK tests, prefer deterministic fakes for streaming/tool-calling sessions.
+
+> **Rationale:** Several bugs in the streaming pipeline (resolveIdle, onComplete fallback) were fixed without tests initially, requiring rework. Writing the test first catches regressions immediately and documents the expected SDK event sequence. Lint and typecheck failures have similarly caused hidden breakage (unused imports, removed interface properties still referenced in tests) that only surfaces at CI time — running them in every iteration prevents that drift.
+
+
+### Agent State Management
+Each agent phase should:
+- Accept context from previous phases
+- Emit structured output for the next phase
+- Support checkpointing for long-running sessions
+
+### Prompt Engineering
+
+- Canonical prompts used by the runtime should live in `src/prompts/`.
+- `src/originalPrompts/` is for inspiration/legacy examples; it is not the source of truth for production prompts.
+- Use markdown format for prompt templates
+- Include few-shot examples where applicable
+- Reference the [AI Discovery Cards Agent Guide](https://github.com/microsoft-partner-solutions-ai/agent-guides/tree/main/ai-discovery-cards-agent) for:
+  - System instructions and workshop methodology
+  - Knowledge sources and suggested prompts
+  - Uploaded reference files (workshop materials, card decks)
+
+### Import Ordering & Linting
+
+The project uses ESLint with `eslint-plugin-import` and the `import/order` rule set to `warn`. Imports **must** be separated into groups with a blank line between each group:
+
+1. **Built-in / External** — Node.js built-ins and `node_modules` packages (e.g., `commander`, `vitest`, `pino`)
+2. **Internal / Parent / Sibling** — Project-relative imports (e.g., `../shared/schemas/session.js`)
+
+```typescript
+// ✅ Correct — blank line between groups
+import { Command } from 'commander';
+
+import type { PhaseValue } from '../shared/schemas/session.js';
+
+// ❌ Wrong — no blank line between external and internal
+import { Command } from 'commander';
+import type { PhaseValue } from '../shared/schemas/session.js';
+```
+
+**Run `npm run lint` after every code change — not just at the end.** Lint failures block commits the same way failing tests do. If the linter reports `import/order` warnings, add blank lines between the import groups.
+
+### Typecheck
+
+The project enforces strict TypeScript checking via `npm run typecheck` (`tsc --noEmit`). **Run `npm run typecheck` after every code change — not just at the end.** Typecheck failures block commits the same way failing tests do.
+
+1. Run `npm run typecheck` and fix all errors before proceeding to the next step.
+2. Never suppress errors with `@ts-ignore` or `any` — use proper types, type narrowing, or Vitest's `Mock<>` generic.
+3. For third-party packages without `@types`, add an ambient module declaration in `src/types/<package>.d.ts`.
+
+> **Rationale:** Type mismatches between production code and Zod schemas (e.g., wrong property names in `exportWriter.ts`) were only caught by strict typechecking, not by tests. Unused imports left behind after interface refactoring (e.g., removing `githubAdapter` from `RalphLoopOptions`) caused silent CI failures that would have been caught immediately by running `npm run lint && npm run typecheck` in every loop iteration.
+
+## MCP Server Configuration
+
+The project uses Model Context Protocol servers for external integrations. Configuration is in:
+- `.vscode/settings.json` - VS Code / GitHub Copilot integration
+- `.vscode/mcp.json` - MCP server configuration
+
+Ensure these services are being used when needed for context retrieval and tool calls in the agent flow.
+
+### Available MCP Servers
+
+| Server | Config | Purpose |
+|--------|--------|---------|
+| `workiq` | `@microsoft/workiq` | Microsoft 365 data - emails, meetings, documents, Teams messages |
+| `github` | Remote: `https://api.githubcopilot.com/mcp/` | Repository search, code, issues, PRs, Actions workflows |
+| `microsoftdocs` | Remote: `https://learn.microsoft.com/api/mcp` | Azure resource management - storage, compute, databases and everything else |
+| `context7` | `@upstash/context7-mcp` | Up-to-date library/framework documentation |
+| `playwright` | `@playwright/mcp@latest` | Browser automation for web research and PoC testing |
+
+> **Note**: Web search is built into GitHub Copilot - no additional MCP server needed for researching companies, industry trends, or public information.
+
+### WorkIQ Setup
+
+WorkIQ requires Microsoft 365 tenant access and admin consent. On first use:
+1. Run `npx -y @microsoft/workiq accept-eula` to accept the EULA
+2. Sign in when prompted - admin consent may be required
+3. See [WorkIQ Admin Instructions](https://github.com/microsoft/work-iq-mcp/blob/main/ADMIN-INSTRUCTIONS.md) for tenant setup
+
+## Terminal Command Safety
+
+The CLI solution may hang or get stuck during development (e.g., interactive prompts waiting for input, infinite loops, watch modes). To avoid blocking the agent:
+
+- **Always use a timeout** when running `npm test`, `npm run build`, `npm run dev`, or any command that could hang. Use the `timeout` parameter on terminal calls (e.g., 30000ms for tests, 60000ms for builds).
+- **Never run `npm run dev` without a timeout** — it starts a watch process that never exits on its own.
+- **Prefer targeted test runs** (`npm test -- <specific-file>`) over full suite runs when iterating on a single module.
+- **If a command hangs**, kill it and investigate the root cause rather than waiting indefinitely.
+
+## Security Considerations
+
+- Never log or expose user tokens
+- Use the SDK's built-in request verification rather than custom implementations
+- Follow [AIDA's RAI principles](https://github.com/microsoft/ai-discovery-agent/blob/main/docs/RESPONSIBLE_AI_PRINCIPLES.md) for AI transparency

package/.github/prompts/speckit.analyze.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.analyze
+---

package/.github/prompts/speckit.checklist.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.checklist
+---

package/.github/prompts/speckit.clarify.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.clarify
+---

package/.github/prompts/speckit.constitution.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.constitution
+---

package/.github/prompts/speckit.implement.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.implement
+---

package/.github/prompts/speckit.plan.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.plan
+---

package/.github/prompts/speckit.specify.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.specify
+---

package/.github/prompts/speckit.tasks.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.tasks
+---

package/.github/prompts/speckit.taskstoissues.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.taskstoissues
+---

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npm run typecheck      
+      
+      - name: Run tests
+        env:
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_KEY }}
+          GITHUB_TOKEN: ${{ secrets.COPILOT_KEY }}
+        run: npm test

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "semi": true
+}

package/.specify/memory/constitution.md

@@ -0,0 +1,181 @@
+<!--
+Sync Impact Report
+
+- Version change: 1.1.1 → 1.1.2
+- Modified principles: none
+- Clarifications: added explicit mapping between 12-step process and Discover/Ideate/Design/Select/Plan/Develop wording
+- Added sections: Sync Impact Report (this comment)
+- Removed sections: none
+- Templates requiring updates:
+  - ✅ .specify/templates/plan-template.md (Constitution Check gates clarified)
+  - ✅ .specify/templates/tasks-template.md (tests/TDD requirements aligned)
+  - ✅ .github/copilot-instructions.md (repo structure + TDD guidance aligned)
+  - ⚠ .specify/templates/commands/*.md (folder not present in this repo)
+- Deferred TODOs: none
+-->
+
+# sofIA Copilot CLI Constitution
+
+This constitution governs the design, development, and operation of the sofIA Copilot CLI solution. The system helps organizations **analyze, ideate, design, generate, and select** high‑quality AI‑enabled project ideas using the AI Discovery Cards methodology, implemented with the GitHub Copilot SDK for Node.js.
+
+## Core Principles
+
+### I. Outcome‑First AI Discovery
+
+- The primary goal is to help users discover, refine, and prioritize valuable, feasible AI use cases – **not** to generate code for its own sake.
+- The agent always keeps the AI Discovery Cards workshop phases in view: Discover → Ideate → Design → Select → Plan → Develop.
+- All outputs (text, plans, code suggestions) must explicitly tie back to business goals, users, processes, and measurable impact.
+
+### II. Secure‑by‑Default & Privacy‑Respecting
+
+- Follow **least privilege**: only request and use the minimum data, scopes, repos, and MCP capabilities required for the current task.
+- Never log, echo, or persist secrets, access tokens, PII, or customer‑sensitive data.
+- When using external MCP services or web fetch, prefer **anonymized, aggregate, or redacted** context; avoid copying proprietary content into prompts unless the user explicitly provides it.
+- Default to local execution where possible; remote calls must be transparent and justifiable.
+
+### III. Node.js + TypeScript, SDK‑Aligned
+
+- The solution is implemented in **Node.js (LTS) with TypeScript**, using the GitHub Copilot SDK for Node.js as the primary integration surface.
+- All core behavior (request parsing, streaming events, MCP calls, orchestration) must follow SDK best practices and patterns established in this repository.
+- Public contracts (CLI flags, JSON schemas, extension event formats) are treated as **APIs** and evolved carefully.
+
+### IV. MCP‑First Context & Tools
+
+- Prefer **MCP servers** over ad‑hoc HTTP calls whenever suitable tools exist (Context7, Playwright, WorkIQ, Microsoft Docs, GitHub MCP, filesystem, fetch, etc.).
+- Each MCP call must have a **clear purpose** that supports the current workshop phase (e.g., research technology options, inspect existing codebases, understand documentation, analyze processes).
+- Tool use is **explainable**: the agent should be able to state what tool it used, why, and how the result influenced its recommendation.
+
+### V. Test‑First, Regressions‑Last (Red → Green → Lint → Review)
+
+- New behavior must be covered by **automated tests** (unit where possible, integration/e2e where necessary).
+- **No implementation starts before tests**: for every task phase, the first committed change MUST be failing tests that describe the target behavior.
+- The project follows a **phase‑level TDD cycle** for every feature implemented:
+  1. **Red**: Write all tests for the current task phase **before** writing any implementation code. All new tests MUST fail initially, confirming they test real behavior that does not yet exist.
+  2. **Green**: Implement the minimum code needed to make all failing tests pass. Do not move to the next phase until every test is green.
+  3. **Lint**: After green, run `npm run lint && npm run typecheck`. **Both must pass before any commit.** Lint and typecheck failures are treated the same as failing tests — stop, fix, re‑verify. This step is mandatory in every iteration, not just at the end of a task.
+  4. **Review**: After lint passes, perform a **mandatory self‑review** using the Test Review Checklist (see Development Workflow below) to identify gaps. Add new tests if gaps are found and repeat the red → green → lint cycle for those additions.
+- **Loop invariant for every code change**: run `npm run lint && npm run typecheck` immediately after editing any file. Never commit code that fails either check.
+- Critical flows – idea evaluation, scoring, selection, and project planning – require **stable, deterministic tests** that avoid flaky external dependencies.
+- Interactive CLI flows (menus, phase gates, follow-up prompts, retries, resume, and Ctrl+C paths) MUST be testable from day one through deterministic automation, not only manual checks.
+- Test strategy: pure logic → unit tests; orchestration and tool integration → integration tests with fakes/mocks and a minimal set of live MCP smoke tests.
+- Generated PoC repositories MUST include **basic smoke/happy‑path tests** that validate the code runs successfully. Full TDD is not required for PoC code, but generated tests serve as a quality signal for the Ralph loop.
+- Each **Ralph loop iteration** MUST be test‑driven: every refinement cycle starts with a failing test or captured error that proves a defect exists, refines code until the failure is resolved, runs lint + typecheck, and then checks whether new issues were introduced.
+
+### VI. Interactive CLI Testability by Design
+
+- Every interactive feature MUST define a machine-testable contract up front: expected prompts, user choices, streamed activity signals, decision gates, and terminal end states.
+- The project MUST maintain an automated interactive harness capable of validating full workshop behavior (including phase transitions and governed progression) in a pseudo-terminal environment.
+- For LLM-involved interactive validation, tests MUST use a layered approach:
+  1. deterministic assertions on structure and control flow (menus, summaries, decisions, transitions),
+  2. optional semantic validation (e.g., LLM-as-judge) for quality-sensitive phases.
+- When interaction complexity requires it, the harness MAY use Copilot SDK-generated answer banks or tool-assisted inputs, but runs MUST remain reproducible via saved transcripts/reports and explicit pass/fail checks.
+- A feature is not complete unless at least one automated end-to-end interactive scenario validates the happy path and one validates a failure/recovery path.
+
+### VII. Deterministic, Auditable Agent Behavior
+
+- Prompts, system instructions, and agent flows must be **versioned and reviewable** (stored under `src/prompts` or equivalent, not embedded ad‑hoc everywhere).
+- For the same inputs and configuration, the system should aim for **predictable, reproducible** outputs (within the limits of LLM variability), achieved via structured prompts, stable scoring rubrics, and constrained response schemas.
+- Significant decisions (e.g., why an AI idea was ranked #1 vs #2) should be accompanied by **structured rationale** suitable for audit and stakeholder review.
+
+### VIII. CLI‑First UX & Transparency
+
+- The CLI interface is a **first‑class product**: clear commands, help text, and progress reporting are mandatory.
+- All long‑running operations (multi‑phase workshops, MCP orchestrations) must **stream progress**, not leave users idle.
+- Users MUST always see the current execution state (current phase, waiting for input, running tool/action, retry/recovery state) during interactive and long-running operations.
+- On failures, user-facing output MUST include: what failed, why it likely failed, what was already completed, and the next actionable recovery options.
+- The agent must be honest about limitations, uncertainty, and trade‑offs, avoiding over‑confident claims.
+
+## Architecture & Scope
+
+- The system implements the AI Discovery Cards process as a **multi‑phase agentic pipeline**:
+  - First phase is the AI Discovery Cards 12-step process
+  - Phase 2: idea selection
+  - Phase 3: Planning and development, outline milestones, dependencies, and PoC scope. Finally generate PoC‑level code examples and scaffolding.
+
+Mapping: the 12-step workshop covers **Discover/Ideate/Design**; Phase 2 maps to **Select**; Phase 3 maps to **Plan/Develop**.
+
+- Each step is implemented as a **composable agent/module** with:
+  - A narrow responsibility and input/output contract.
+  - A clear hand‑off format to the next phase.
+  - Optional checkpointing/check‑in with the user (especially at selection & planning).
+- The Copilot CLI acts as an **orchestrator**, not a monolith: orchestration code wires agents, prompts, and MCP tools together.
+
+## Security & Compliance
+
+- Always validate CLI arguments, configuration files, and Copilot SDK session payloads before processing.
+- Enforce strict **input validation** on CLI arguments, configuration files, and environment variables; fail fast on invalid or unsafe values.
+- Use secure defaults:
+  - HTTPS‑only when calling remote services.
+  - TLS verification enabled; no blanket `NODE_TLS_REJECT_UNAUTHORIZED=0`.
+  - Timeouts and retries configured to avoid hanging processes.
+- Access to GitHub, Azure, WorkIQ, or other enterprise systems must respect **organization policies** and least‑privilege scopes.
+- Sensitive outputs (like architecture diagrams or PoC code that touches regulated data) should include **disclaimers and risk notes** when appropriate.
+
+## MCP Services Usage
+
+- **Context7**
+  - Use to fetch **up‑to‑date documentation and best practices** for libraries, frameworks, and platforms relevant to a proposed AI idea.
+  - Use when evaluating technical feasibility, comparing implementation options, or generating PoC scaffolding.
+  - Prefer official or high‑trust sources; clearly separate factual documentation from generated interpretation.
+
+- **Playwright MCP**
+  - Use for **browser automation and validation** when ideas involve web UX, customer journeys, or site workflows.
+  - Suitable tasks: walking through existing user flows, capturing page structure, or validating that an AI augmentation can integrate into a target UI.
+  - Avoid using it to capture or persist sensitive user data; respect robots.txt and customer security guidelines.
+
+- **WorkIQ / M365 MCP** (when enabled)
+  - Use for **process discovery** and empirical analysis of how work is currently performed (emails, meetings, documents, Teams, etc.).
+  - Only access tenants and scopes explicitly authorized; never assume cross‑tenant access.
+  - Summaries and suggestions must preserve confidentiality and avoid exposing individual‑level behavioral analytics unless policy allows.
+
+- **GitHub MCP**
+  - Use to analyze existing repos and workflows when ideas involve **developer productivity, DevOps, or code quality**.
+  - Prefer light‑touch analysis (metadata, structure, high‑level patterns) over raw code dumps unless the user explicitly requests deeper review.
+
+- **Microsoft Docs / Azure MCP**
+  - Use for authoritative **cloud architecture, security, and compliance** guidance when proposing Azure‑based or Microsoft‑based solutions.
+  - When generating Azure/AI solution ideas, ground recommendations in official docs where feasible.
+
+## Development Workflow & Quality Gates
+
+- **Branching & Reviews**
+  - All substantial changes (logic, prompts, workflows) go through PRs and human review.
+  - PR descriptions must state which workshop phases are affected and which tests were run.
+
+- **Testing Requirements (Red → Green → Review)**
+  - A change is not done until there are passing tests covering the new behavior.
+  - The first implementation commit for a task phase MUST include failing tests before production-code changes.
+  - Core scoring and selection logic must have **high‑signal unit tests** (no reliance on live LLMs or MCP tools for correctness).
+  - End‑to‑end tests may stub LLMs/MCPs while validating orchestration and CLI UX.
+  - To generate proper non-stub integration LLM tests, GitHub Copilot SDK can help, keep in mind that results are non-deterministic.
+  - Interactive CLI changes MUST include automated terminal-flow tests that verify prompts, user decisions, transitions, and persistence/resume behavior.
+  - LLM-dependent behavior MUST expose deterministic checks first (schema/control flow/required signals), with optional semantic checks layered on top.
+  - Every task phase follows the **phase‑level TDD cycle**: tests written first → all must fail → implement until green → self‑review.
+  - After reaching green, the implementer MUST run through the **Test Review Checklist**:
+    - [ ] Are all edge cases covered (empty inputs, nulls, boundary values)?
+    - [ ] Are negative/error paths tested (invalid data, missing dependencies, permission failures)?
+    - [ ] Are boundary conditions verified (max/min values, empty collections, large payloads)?
+    - [ ] Are new integration points exercised (new MCP calls, Copilot SDK interactions)?
+    - [ ] Do existing tests still pass without modification (no silent regressions)?
+    If any gaps are found, add tests and repeat the red → green cycle before proceeding.
+
+- **Observability & Diagnostics**
+  - Use structured, leveled logging with a clear separation between **debug**, **info**, **warn**, and **error**.
+  - Logging MUST be extensive enough to reconstruct interactive failures end-to-end: include session ID, phase, turn number, tool/action, timing, and transition decisions.
+  - Logs must never contain secrets or sensitive data; link to resource identifiers or hashes instead.
+  - For CLI users, provide concise error messages plus an optional `--verbose` or `--debug` mode.
+  - Interactive UX MUST surface real-time operational events to users (progress, tool activity, state changes) and provide explicit failure reasons with recovery guidance.
+  - Automated interactive runs MUST persist artifacts (for example: transcript + structured report) so regressions are diagnosable and reproducible.
+
+## Governance
+
+- This constitution **supersedes ad‑hoc practices** for the sofIA Copilot CLI and related agents.
+- Any feature, design, or prompt that conflicts with this document must be revised or justified via a documented exception.
+- Amendments require:
+  - A proposal documenting the motivation, risks, and migration/rollout plan.
+  - Review and approval via the project’s standard PR process.
+  - A version bump and date update in this file.
+- All PR reviews should include an explicit, light‑weight check against this constitution: security, testing, MCP usage, and AI Discovery alignment.
+- Runtime guidance (coding style, prompts, agent composition) should be kept in the project’s developer docs and referenced from here as needed.
+
+**Version**: 1.1.2 | **Ratified**: 2026-02-24 | **Last Amended**: 2026-02-26