sofia-cli 0.1.1

package/docs/cli-usage.md

@@ -0,0 +1,207 @@
+# CLI Usage
+
+## Binary
+
+The CLI is invoked via `npm run start --` (development) or `sofia` (after building and linking).
+
+```bash
+# Development mode (tsx, no watch)
+npm run start -- <command> [options]
+
+# Watch mode (auto-reloads on file changes)
+npm run dev -- <command> [options]
+
+# Built mode (requires `npm run build` first)
+npm run sofia -- <command> [options]
+```
+
+## Global Options
+
+| Flag                | Description                                                         |
+| ------------------- | ------------------------------------------------------------------- |
+| `--version`         | Print version and exit                                              |
+| `--help`            | Print help and exit                                                 |
+| `--session <id>`    | Target a specific session by ID                                     |
+| `--json`            | Machine-readable JSON output only on stdout                         |
+| `--debug`           | Enable debug telemetry                                              |
+| `--log-file <path>` | Write structured logs to the specified file                         |
+| `--non-interactive` | Disallow prompts; fail with an actionable error if input is missing |
+
+## Commands
+
+### `workshop`
+
+Start or resume a governed AI Discovery Workshop session.
+
+```bash
+# Interactive: shows a menu to start new or resume existing session
+npm run start -- workshop
+
+# Start a new session directly
+npm run start -- workshop --new-session
+
+# Direct command mode: run a specific phase on an existing session
+npm run start -- workshop --session <id> --phase Discover
+
+# With retry for transient failures
+npm run start -- workshop --session <id> --phase Ideate --retry 3
+```
+
+**Workshop-specific flags:**
+
+| Flag              | Description                                            |
+| ----------------- | ------------------------------------------------------ |
+| `--new-session`   | Skip menu and start a new session                      |
+| `--phase <phase>` | Jump to a specific phase (requires `--session`)        |
+| `--retry <count>` | Retry transient failures N times (direct command mode) |
+
+**Phases** (in order): `Discover`, `Ideate`, `Design`, `Select`, `Plan`, `Develop`
+
+**Direct command mode** is activated when both `--session` and `--phase` are specified. In this mode:
+
+- The workshop runs the specified phase without the interactive menu
+- Supports `--non-interactive` for automation (fails fast if input is missing)
+- Supports `--retry` to retry recoverable errors with exponential backoff
+- `--json` constrains stdout to JSON-only (activity goes to stderr)
+
+### `status`
+
+Display session status and next expected action.
+
+```bash
+# Human-readable table
+npm run start -- status
+
+# JSON output for a specific session
+npm run start -- status --session <id> --json
+```
+
+**Output formats:**
+
+- **TTY (human):** A table showing session ID, current phase, status, and last update time
+- **JSON mode:** `{ "sessions": [{ "sessionId", "phase", "status", "updatedAt" }] }` or `{ "session": { ... } }` for a single session
+
+### `dev`
+
+Run the **Develop** phase for a completed workshop session. Generates a proof-of-concept (PoC) repository using a Ralph loop — an autonomous, iterative cycle where code is generated, tests run, failures fed back to the LLM, and fixes applied until tests pass or the iteration limit is reached.
+
+```bash
+# Generate a PoC from a completed session (uses most recent session by default)
+npm run start -- dev
+
+# Target a specific session
+npm run start -- dev --session <id>
+
+# Limit iterations and specify output directory
+npm run start -- dev --session <id> --max-iterations 5 --output ./my-poc
+
+# Overwrite existing output and start fresh
+npm run start -- dev --session <id> --force
+
+# Machine-readable JSON output
+npm run start -- dev --session <id> --json
+```
+
+**Dev-specific flags:**
+
+| Flag                   | Description                                                  |
+| ---------------------- | ------------------------------------------------------------ |
+| `--session <id>`       | Session ID (defaults to most recent session)                 |
+| `--max-iterations <n>` | Maximum Ralph loop iterations (default: 10)                  |
+| `--output <dir>`       | Output directory for the PoC (default: `./poc/<sessionId>/`) |
+| `--force`              | Overwrite existing output directory and start fresh          |
+| `--json`               | Machine-readable JSON output                                 |
+| `--debug`              | Show iteration events during execution                       |
+
+**Lifecycle:**
+
+1. **Validate** — Checks the session has `selection` and `plan` populated (from Select and Plan phases)
+2. **Scaffold** — Creates the initial PoC project structure (README, package.json, tsconfig.json, tests, etc.)
+3. **Install** — Runs `npm install` in the PoC directory
+4. **Iterate** — Runs tests → feeds failures to LLM → applies code changes → repeats
+5. **Terminate** — Stops when tests pass, max iterations reached, or user presses Ctrl+C
+
+**GitHub MCP integration:**
+When GitHub MCP is available and authorized, the PoC is also pushed to a GitHub repository. When unavailable, it falls back to local-only output with a clear log message.
+
+**JSON output format** (with `--json`):
+
+```json
+{
+  "sessionId": "abc123",
+  "finalStatus": "success",
+  "terminationReason": "tests-passing",
+  "iterationsCompleted": 4,
+  "repoSource": "local",
+  "repoPath": "./poc/abc123/",
+  "outputDir": "/absolute/path/to/poc/abc123"
+}
+```
+
+**Recovery options** (shown on non-success outcomes):
+
+```bash
+# Resume from where you left off
+sofia dev --session <id>
+
+# Allow more iterations
+sofia dev --session <id> --max-iterations 20
+
+# Start fresh
+sofia dev --session <id> --force
+```
+
+### `export`
+
+Export workshop artifacts for a session.
+
+```bash
+# Export to default directory (./exports/<sessionId>/)
+npm run start -- export --session <id>
+
+# Export to a custom directory
+npm run start -- export --session <id> --output ./my-export/
+```
+
+**Export-specific flags:**
+
+| Flag             | Description                                                 |
+| ---------------- | ----------------------------------------------------------- |
+| `--output <dir>` | Custom output directory (default: `./exports/<sessionId>/`) |
+
+## Exit Codes
+
+| Code | Meaning                                                |
+| ---- | ------------------------------------------------------ |
+| `0`  | Success                                                |
+| `1`  | General error (invalid input, session not found, etc.) |
+
+In JSON mode, errors are emitted as JSON objects with a consistent envelope:
+
+```json
+{
+  "error": {
+    "code": "SESSION_NOT_FOUND",
+    "message": "Session \"abc\" not found."
+  }
+}
+```
+
+## Examples
+
+```bash
+# Full interactive workshop flow
+npm run start -- workshop
+
+# Automation: run Ideate phase, JSON output, no prompts
+npm run start -- workshop --session abc123 --phase Ideate --json --non-interactive
+
+# Check what phase a session is on
+npm run start -- status --session abc123 --json
+
+# Export artifacts after completing a workshop
+npm run start -- export --session abc123
+
+# Enable debug logging to file
+npm run start -- workshop --debug --log-file .sofia/logs/dev.log
+```

package/docs/environment.md

@@ -0,0 +1,66 @@
+# Environment Variables
+
+sofIA uses environment variables for optional integrations. All are optional — the CLI degrades gracefully when they are absent.
+
+## Web Search (Azure AI Foundry)
+
+| Variable                        | Description                                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `FOUNDRY_PROJECT_ENDPOINT`      | Azure AI Foundry project endpoint URL (e.g., `https://<name>.services.ai.azure.com/api/projects/<project>`) |
+| `FOUNDRY_MODEL_DEPLOYMENT_NAME` | Model deployment name for the web search agent (e.g., `gpt-4.1-mini`)                                       |
+
+Both must be set for the `web.search` tool to be available. When not configured, the web search tool is disabled and the workshop proceeds without web search capabilities.
+
+**Authentication:** sofIA authenticates to the Azure AI Foundry Agent Service using `DefaultAzureCredential` from `@azure/identity`. No API key is required — ensure you are logged in via `az login` or have another credential available (Managed Identity, environment variables, etc.).
+
+### Migrating from Legacy Configuration
+
+If you previously used `SOFIA_FOUNDRY_AGENT_ENDPOINT` / `SOFIA_FOUNDRY_AGENT_KEY`:
+
+1. **Remove** the old variables from your environment
+2. **Set** the new variables (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`)
+3. **Ensure** you are logged in via `az login`
+
+The CLI will display an error if it detects the old variables, guiding you through the migration.
+
+> **Note**: `SOFIA_FOUNDRY_AGENT_ENDPOINT` and `SOFIA_FOUNDRY_AGENT_KEY` are no longer used. API key authentication has been replaced by Azure Identity credentials.
+
+## Testing
+
+| Variable               | Description                                                                                                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `SOFIA_LIVE_MCP_TESTS` | Set to `true` to enable end-to-end tests that require real MCP server access and external API calls (e.g., web search). Default: `false` |
+
+These tests are skipped by default because they:
+
+- Require external service credentials
+- May incur API costs
+- Have longer execution times
+- Depend on live network access
+
+To run live tests:
+
+```bash
+export SOFIA_LIVE_MCP_TESTS=true
+npm test  # or npm run test:e2e
+```
+
+## Copilot SDK
+
+The `@github/copilot-sdk` reads its own environment variables for authentication. Refer to the [Copilot SDK documentation](https://github.com/github/copilot-sdk) for details.
+
+## Logger Redaction
+
+The following field names are automatically redacted in structured logs:
+
+- `password`
+- `token`
+- `secret`
+- `apiKey`
+- `api_key`
+- `authorization`
+- `auth`
+- `credential`
+- `credentials`
+
+Any log entry containing these field names will have their values replaced with `[REDACTED]`.

package/docs/export-format.md

@@ -0,0 +1,146 @@
+# Export Format
+
+## Overview
+
+The `sofia export` command generates customer-ready artifacts from a workshop session. Exports include per-phase Markdown files and a machine-readable `summary.json`.
+
+## Output Directory
+
+```
+exports/<sessionId>/
+├── summary.json
+├── discover.md
+├── ideate.md
+├── design.md
+├── select.md
+├── plan.md
+└── develop.md
+```
+
+Default path: `./exports/<sessionId>/`
+Override with: `--output <dir>`
+
+## summary.json
+
+The summary file provides a machine-readable overview of the export.
+
+```json
+{
+  "sessionId": "ac516a6f-f5ee-4426-9a61-4d5c9c883ba7",
+  "exportedAt": "2026-02-27T10:30:00.000Z",
+  "phase": "Plan",
+  "status": "Active",
+  "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": "summary.json", "type": "json" }
+  ],
+  "highlights": [
+    "Business: Contoso Ltd — supply chain optimization",
+    "Selected idea: AI-powered demand forecasting",
+    "Plan: 3 milestones over 8 weeks"
+  ]
+}
+```
+
+### Fields
+
+| Field        | Type                  | Description                                            |
+| ------------ | --------------------- | ------------------------------------------------------ |
+| `sessionId`  | `string`              | Session identifier                                     |
+| `exportedAt` | `string`              | ISO-8601 timestamp of export                           |
+| `phase`      | `string`              | Session phase at time of export                        |
+| `status`     | `string`              | Session status at time of export                       |
+| `files`      | `Array<{path, type}>` | List of generated files (paths relative to export dir) |
+| `highlights` | `string[]?`           | Optional key takeaways from the session                |
+
+## Phase Markdown Files
+
+Each completed phase generates a Markdown file with phase-specific content:
+
+| File          | Contents                                                       |
+| ------------- | -------------------------------------------------------------- |
+| `discover.md` | Business description, challenges, constraints, topic selection |
+| `ideate.md`   | Activities, workflow map, selected AI Envisioning Cards        |
+| `design.md`   | Idea Cards with descriptions and architecture sketches         |
+| `select.md`   | Evaluation matrix, selected idea, rationale                    |
+| `plan.md`     | Implementation milestones, architecture notes, dependencies    |
+| `develop.md`  | PoC repository, tech stack, iteration history, test results    |
+
+Only phases that have been completed (or are in progress) generate Markdown files. If a phase has no data, its file is omitted.
+
+### develop.md — Detailed Structure
+
+The Develop export is generated from `PocDevelopmentState` and includes:
+
+| Section                | Content                                                                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **PoC Repository**     | Local path (always local git repository), plus `repoSource` (`local`). Users push manually to GitHub when ready (safer approach).                |
+| **Technology Stack**   | Language, runtime, test runner, framework (optional), build command (optional)                                                                   |
+| **Result**             | `finalStatus` (`success`, `failed`, `partial`), `terminationReason` (`tests-passing`, `max-iterations`, `user-stopped`, `error`), total duration |
+| **Final Test Results** | Passed/failed/skipped counts, duration, per-failure details (test name, message, expected/actual, file/line)                                     |
+| **Iteration Timeline** | Per-iteration: outcome, duration, changes summary, files changed, test results, error messages                                                   |
+
+Example structure:
+
+```markdown
+# Develop Phase
+
+## PoC Repository
+
+**Repository Path**: ./poc/abc123/
+**Source**: local
+
+## Technology Stack
+
+- **Language**: TypeScript
+- **Runtime**: Node.js 20
+- **Test Runner**: vitest
+
+## Result
+
+**Status**: success
+**Termination Reason**: tests-passing
+**Total Duration**: 45.2s
+
+## Final Test Results
+
+- **Passed**: 5
+- **Failed**: 0
+- **Skipped**: 0
+- **Total**: 5
+- **Duration**: 1200ms
+
+## Iteration Timeline
+
+### Iteration 1 — scaffold (2.1s)
+
+Initial project scaffolding
+**Files changed**: README.md, package.json, tsconfig.json, ...
+
+### Iteration 2 — tests-failing (8.3s)
+
+Added core implementation
+**Files changed**: src/index.ts, tests/index.test.ts
+**Tests**: 3 passed, 2 failed, 0 skipped (950ms)
+
+### Iteration 3 — tests-passing (12.5s)
+
+Fixed validation logic
+**Files changed**: src/index.ts
+**Tests**: 5 passed, 0 failed, 0 skipped (1100ms)
+```
+
+## Safety
+
+- No secrets or tokens are included in exports
+- File paths in `summary.json` are relative to the export directory
+- Export is idempotent — re-exporting overwrites previous artifacts
+
+## Related
+
+- Export contract: [specs/001-cli-workshop-rebuild/contracts/export-summary-json.md](../specs/001-cli-workshop-rebuild/contracts/export-summary-json.md)
+- Export writer source: `src/sessions/exportWriter.ts`

package/docs/session-model.md

@@ -0,0 +1,113 @@
+# Session Model
+
+## Overview
+
+A **WorkshopSession** is the central data structure persisted throughout a workshop. It captures all artifacts from each phase and supports resume, backtracking, and export.
+
+## Storage
+
+- **Path:** `.sofia/sessions/<sessionId>.json`
+- **Format:** UTF-8 JSON, overwritten atomically after every user turn
+- **Schema versioning:** `schemaVersion` field enables forward migration
+
+## Session Lifecycle
+
+```
+New Session → Active (Discover) → ... → Active (Plan) → Active (Develop) → Completed
+                  ↕                          ↕
+               Paused                     Paused
+                  ↕                          ↕
+               Active                     Active
+                  ↓                          ↓
+               Errored                    Errored
+```
+
+### States
+
+| Status | Description |
+|--------|-------------|
+| `Active` | Session is in progress |
+| `Paused` | Session paused (can resume) |
+| `Completed` | All phases finished |
+| `Errored` | Failed with an error (session is persisted before exit) |
+
+## Phases
+
+Phases follow a strict linear progression with decision gates:
+
+```
+Discover → Ideate → Design → Select → Plan → Develop → Complete
+```
+
+| Phase | Purpose | Key Artifacts |
+|-------|---------|---------------|
+| **Discover** | Understand the business, challenges, and context | `businessContext`, `topic` |
+| **Ideate** | Brainstorm activities, explore AI Envisioning Cards | `activities`, `cards` |
+| **Design** | Generate and refine Idea Cards with architecture sketches | `ideas` |
+| **Select** | Evaluate ideas via feasibility/value matrix, pick the best | `evaluation`, `selection` |
+| **Plan** | Create implementation roadmap and milestones | `plan` |
+| **Develop** | Capture PoC requirements and intent (handoff to feature 002) | `poc` |
+
+### Decision Gates
+
+Phase transitions require explicit user confirmation. The system will **never** auto-advance to the next phase. After each phase completes, the user is prompted with a "Proceed to next phase?" decision gate.
+
+### Backtracking
+
+Users can backtrack to an earlier phase. When backtracking:
+- All downstream phase artifacts are **invalidated** (marked for recomputation)
+- The session moves to the target phase
+- Invalidated phases must be re-run to regenerate their artifacts
+
+## Session Fields
+
+```typescript
+interface WorkshopSession {
+  sessionId: string;              // Stable UUID
+  createdAt: string;              // ISO-8601
+  updatedAt: string;              // ISO-8601, monotonically increasing
+  schemaVersion: string;          // e.g., "1.0.0"
+  phase: Phase;                   // Current phase
+  status: SessionStatus;          // Active | Paused | Completed | Errored
+  participants: Participant[];    // Facilitator, attendees, observers
+  businessContext?: BusinessContext;
+  topic?: TopicSelection;
+  activities?: Activity[];
+  workflow?: WorkflowMap;
+  cards?: CardSelection;
+  ideas?: IdeaCard[];
+  evaluation?: IdeaEvaluation;
+  selection?: SelectedIdea;
+  plan?: ImplementationPlan;
+  poc?: PocDevelopmentState;
+  artifacts: ArtifactIndex;
+  errors?: ErrorRecord[];
+}
+```
+
+### Key Sub-entities
+
+| Entity | Purpose |
+|--------|---------|
+| `BusinessContext` | Company description, challenges, constraints, success metrics |
+| `TopicSelection` | Chosen focus area and scope notes |
+| `WorkflowMap` | Steps and edges describing the activity flow |
+| `CardSelection` | Selected AI Envisioning Cards with scores |
+| `IdeaCard` | Generated ideas with title, description, workflow links |
+| `IdeaEvaluation` | Feasibility/value scoring for each idea |
+| `SelectedIdea` | The chosen idea with rationale and user confirmation |
+| `ImplementationPlan` | Milestones, architecture notes, dependencies |
+| `PocDevelopmentState` | PoC repo path, iterations, final status |
+
+## Safety
+
+- Secrets and tokens are **never** persisted in session JSON
+- Sensitive values from tool responses are redacted before writing
+- The `schemaVersion` field supports future migrations without data loss
+- Unknown fields are preserved when loading/saving (forward compatibility)
+
+## Related
+
+- Data model spec: [specs/001-cli-workshop-rebuild/data-model.md](../specs/001-cli-workshop-rebuild/data-model.md)
+- Session JSON contract: [specs/001-cli-workshop-rebuild/contracts/session-json.md](../specs/001-cli-workshop-rebuild/contracts/session-json.md)
+- Schema source: `src/shared/schemas/session.ts`

package/eslint.config.js

@@ -0,0 +1,35 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettier from 'eslint-config-prettier';
+import pluginImport from 'eslint-plugin-import';
+
+export default tseslint.config(
+  {
+    ignores: ['node_modules/', 'dist/', 'build/', 'coverage/', '*.min.js', '.sofia/', 'exports/'],
+  },
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  prettier,
+  {
+    plugins: {
+      import: pluginImport,
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+      'import/order': [
+        'warn',
+        {
+          groups: [['builtin', 'external'], 'internal', ['parent', 'sibling', 'index']],
+          'newlines-between': 'always',
+        },
+      ],
+    },
+  },
+);