@mc1global/opencode-jarvis 0.9.0 → 0.11.0

package/README.md

@@ -4,31 +4,44 @@ A native [OpenCode](https://opencode.ai) plugin providing multi-agent developmen
 
 Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
 
+---
+
 ## Prerequisites
 
-| Requirement | Purpose | Required? |
-|---|---|---|
-| [OpenCode](https://opencode.ai) CLI | Host runtime for the plugin | **Yes** |
-| [Bun](https://bun.sh) >= 1.0 | Production runtime (bun:sqlite, MCP server) | **Yes** |
-| Node.js >= 20 | Test runner (Jest + ESM) | Dev only |
-| [Ollama](https://ollama.ai) | Local embedding generation for RAG | For RAG features |
-| `embeddinggemma` model | Default embedding model (768 dims) | For RAG features |
-| [Dagger CLI](https://docs.dagger.io/install) | Container-based CI/CD gate execution | Optional |
-| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | Azure DevOps board sync | Optional |
+- **[OpenCode](https://opencode.ai) CLI** — Host runtime for the plugin (**required**)
+- **[Bun](https://bun.sh) >= 1.0** — Production runtime for bun:sqlite (**required**)
+- **[Ollama](https://ollama.ai)** + `embeddinggemma` model — Local embeddings for RAG semantic search (**required for RAG**)
+- **Node.js >= 20** — Test runner only (dev)
+- **[Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** — Azure DevOps board sync (optional)
+- **[Dagger CLI](https://docs.dagger.io/install)** — Container CI/CD gate execution (optional)
+
+---
 
 ## Quick Start
 
-### 1. Install prerequisites
+### Step 1 — Install prerequisites
+
+Choose your operating system below. Each section includes both **manual commands** and a link to an **automated setup script** that handles everything.
+
+#### macOS
+
+**Automated** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-macos.sh | bash
+```
+
+Or download `scripts/setup/setup-macos.sh` from the repository and run it locally.
 
-**macOS:**
+**Manual:**
 
 ```bash
 # Bun (required — SQLite runtime)
 curl -fsSL https://bun.sh/install | bash
 
-# Ollama (required — RAG semantic search)
+# Ollama + embedding model (required for RAG)
 brew install ollama
-ollama serve                    # start the server
+ollama serve                    # start the server (keep running)
 ollama pull embeddinggemma      # download the embedding model
 
 # Optional: Azure DevOps sync
@@ -38,42 +51,154 @@ brew install azure-cli && az login
 brew install dagger/tap/dagger
 ```
 
-**Linux:**
+#### Linux (Ubuntu/Debian/Fedora/Arch)
+
+**Automated** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-linux.sh | bash
+```
+
+Or download `scripts/setup/setup-linux.sh` from the repository and run it locally.
+
+**Manual:**
 
 ```bash
+# Bun (required)
 curl -fsSL https://bun.sh/install | bash
+
+# Ollama + embedding model (required for RAG)
 curl -fsSL https://ollama.ai/install.sh | sh
-ollama serve && ollama pull embeddinggemma
+ollama serve                    # start the server (keep running)
+ollama pull embeddinggemma      # download the embedding model
+
+# Optional: Azure CLI (Debian/Ubuntu)
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
+
+# Optional: Dagger CLI
+curl -fsSL https://dl.dagger.io/dagger/install.sh | sh
+```
+
+#### Windows (WSL)
+
+> OpenCode recommends Windows Subsystem for Linux (WSL) for the best experience.
+> See the [OpenCode WSL guide](https://opencode.ai/docs/windows-wsl) for details.
+
+**Step 0 — Install WSL** (if you haven't already):
+
+Open **PowerShell as Administrator** and run:
+
+```powershell
+wsl --install
 ```
 
-### 2. Add the plugin to your project
+Restart your computer, then open the **Ubuntu** terminal app.
 
-Create `opencode.json` in your project root:
+**Step 1 — Run the setup script inside WSL:**
+
+```bash
+# From your WSL terminal (Ubuntu):
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-wsl.sh | bash
+```
+
+Or download `scripts/setup/setup-wsl.sh` from the repository and run it inside WSL.
+
+**Manual (inside WSL terminal):**
+
+```bash
+# OpenCode CLI
+curl -fsSL https://opencode.ai/install | bash
+
+# Bun (required)
+curl -fsSL https://bun.sh/install | bash
+
+# Ollama + embedding model (required for RAG)
+curl -fsSL https://ollama.ai/install.sh | sh
+ollama serve                    # start the server (keep running in a separate terminal)
+ollama pull embeddinggemma      # download the embedding model
+
+# Optional: Azure CLI
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
+```
+
+> **WSL performance tip:** For best results, keep your project files in the WSL
+> filesystem (`~/code/my-project`) rather than on `/mnt/c/`. See
+> [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl) for more.
+
+---
+
+### Step 2 — Add the plugin to your project
+
+Create an `opencode.json` file **in your project root directory**:
+
+```
+your-project/              <-- your project root
+  opencode.json            <-- CREATE THIS FILE HERE
+  package.json
+  src/
+  ...
+```
+
+Content of `opencode.json`:
 
 ```json
 {
+  "$schema": "https://opencode.ai/config.json",
   "plugin": ["@mc1global/opencode-jarvis"]
 }
 ```
 
 OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
 
-### 3. First launch (automatic)
+#### Where exactly does `opencode.json` go?
+
+OpenCode supports config files at **two levels**. Choose one (or both — they merge):
+
+**Project-level** (recommended for teams):
+
+```
+/home/you/code/my-project/opencode.json       # Linux/WSL
+/Users/you/code/my-project/opencode.json       # macOS
+```
+
+This is committed to git so your whole team gets the plugin. OpenCode looks for this file in the current directory or traverses up to the nearest git root.
+
+**Global-level** (applies to ALL your projects):
+
+```
+~/.config/opencode/opencode.json               # Linux/macOS/WSL
+```
+
+Use this if you want JARVIS active on every project without adding `opencode.json` to each one.
+
+> **Precedence:** Project config overrides global config for conflicting keys.
+> Non-conflicting settings from both are merged. See the
+> [OpenCode config docs](https://opencode.ai/docs/config#locations) for details.
+
+---
+
+### Step 3 — First launch (automatic)
 
 Run `opencode` in your project directory. JARVIS initializes everything:
 
+```bash
+cd /path/to/your/project    # must contain opencode.json (or have one globally)
+opencode
 ```
-What JARVIS creates automatically on first load:
 
-  .jarvis/                SQLite database + RAG indexes (local, gitignored)
-  config/jarvis.yaml      Default configuration (commit this)
-  obsidian-vault/         Documentation skeleton (commit this)
-  AGENTS.md               Agent operational guide (commit this)
+On first load, JARVIS creates these files and directories automatically:
+
+```
+your-project/
+  .jarvis/                  SQLite database + RAG indexes (local, gitignored)
+  config/jarvis.yaml        Default configuration (commit this)
+  obsidian-vault/           Documentation skeleton (commit this)
+  AGENTS.md                 Agent operational guide (commit this)
 ```
 
 On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
 
-### 4. First session — recommended steps
+### Step 4 — First session recommended steps
 
 The agent should run these on first use (JARVIS prompts automatically):
 
@@ -82,7 +207,7 @@ The agent should run these on first use (JARVIS prompts automatically):
 3. **`rag-oracle-index`** tool with `directory="obsidian-vault"` — Index documentation
 4. **`kanban-board-view`** tool — See the kanban board
 
-### 5. Verify your setup
+### Step 5 — Verify your setup
 
 The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
 
@@ -102,130 +227,108 @@ Summary: 6 pass, 2 warn, 0 fail (8 total)
 Status: HEALTHY
 ```
 
-## What Lives Where
+---
 
-### In Git (committed, shared with team)
+## File Locations Reference
+
+### In your project (committed to git, shared with team)
 
 ```
-opencode.json              Plugin declaration
-config/jarvis.yaml         Configuration (auto-created, then customized)
-AGENTS.md                  Agent operational guide (auto-generated)
-obsidian-vault/            Documentation vault
-.opencode/skills/          Workflow skills for the agent
-.opencode/commands/        Slash commands (/healthcheck, /sync-azure, /start-card)
+your-project/
+  opencode.json              Plugin declaration (Step 2 above)
+  config/jarvis.yaml         Configuration (auto-created, then customized)
+  AGENTS.md                  Agent operational guide (auto-generated)
+  obsidian-vault/            Documentation vault
 ```
 
-### Local per machine (NOT in git)
+### Local per machine (NOT committed — add to .gitignore)
 
 ```
-.jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
-.jarvis/rag/               Vectra vector store (RAG embeddings)
+your-project/
+  .jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
+  .jarvis/rag/               Vectra vector store (RAG embeddings)
 ```
 
-### Global (shared across all projects)
+### Global (shared across all your projects)
 
 ```
-~/.jarvis/registry.db      Workspace registry (cross-project)
-~/.cache/opencode/         Plugin npm cache (managed by OpenCode)
+~/.config/opencode/opencode.json   Global OpenCode config (optional)
+~/.jarvis/registry.db              Workspace registry (cross-project)
+~/.cache/opencode/node_modules/    Plugin npm cache (managed by OpenCode)
 ```
 
-## Available Skills and Commands
-
-### Skills (loaded on demand via `skill()` tool)
-
-| Skill | Description |
-|---|---|
-| `jarvis-onboarding` | Setup, healthcheck, RAG indexing, tool reference |
-| `jarvis-kanban` | Card lifecycle, grooming, sprints, gate tasks |
-| `jarvis-azure-sync` | Azure DevOps push/pull/sync, PR creation |
-
-### Commands (slash commands in any session)
+---
 
-| Command | Description |
-|---|---|
-| `/healthcheck` | Run diagnostics with actionable fix guidance |
-| `/sync-azure` | Execute Azure DevOps sync workflow |
-| `/start-card CD-XXX` | Start working on a kanban card (full lifecycle) |
+## Setup Scripts
 
-## Installation (Local Development)
+Automated setup scripts are available in the `scripts/setup/` directory of this repository. Each script installs all non-npm prerequisites for JARVIS (Bun, Ollama, embedding model) and optionally Azure CLI and Dagger:
 
-```bash
-# Clone
-git clone <repo-url> jarvis-plugin
-cd jarvis-plugin
+- **`scripts/setup/setup-macos.sh`** — macOS with Homebrew
+- **`scripts/setup/setup-linux.sh`** — Ubuntu, Debian, Fedora, Arch Linux
+- **`scripts/setup/setup-wsl.sh`** — Windows Subsystem for Linux (includes OpenCode CLI install + WSL detection)
 
-# Install dependencies
-npm install
+Each script is interactive, checks for existing installations, and clearly reports what it does.
 
-# Build
-npm run build
+---
 
-# Configure in OpenCode (add to your opencode.json)
-{
-  "plugin": {
-    "jarvis": {
-      "path": "/path/to/jarvis-plugin"
-    }
-  }
-}
-```
+## Available Commands
 
-## MCP Server Mode
+Commands are available in any OpenCode session:
 
-JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
+- **`/healthcheck`** — Run diagnostics with actionable fix guidance
+- **`/sync-azure`** — Execute Azure DevOps sync workflow
+- **`/start-card CD-XXX`** — Start working on a kanban card (full lifecycle)
+- **`/config`** — Agent-guided configuration wizard
 
-```bash
-bun run src/mcp-server.ts --directory /path/to/project
-```
+## Available Skills (loaded on demand via `skill()` tool)
 
-Configure tool filtering in `config/jarvis.yaml`:
+- **`jarvis-kanban`** — Card lifecycle, grooming, sprints, gate tasks
+- **`jarvis-azure-sync`** — Azure DevOps push/pull/sync, PR creation
+- **`jarvis-onboarding`** — Setup, healthcheck, RAG indexing, tool reference
 
-```yaml
-mcp-server:
-  transport: "stdio"
-  enabledTools: null  # null = all tools, or list specific tool names
-```
+---
 
 ## Features
 
-### 113 Tools across 14 categories
-
-| Category | Count | Key Tools |
-|---|---|---|
-| **Context Memory** | 8 | `context-session-*`, `context-todo-*`, `context-note-*`, `context-search` |
-| **Kanban Cards** | 12 | `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief` |
-| **Kanban Board** | 15 | `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check` |
-| **Kanban Grooming** | 4 | `kanban-grooming-validate`, `kanban-card-scope-doc/criteria/estimate`, `kanban-card-gate` |
-| **Governance** | 2 | `governance-validate`, `governance-policies` |
-| **Token Metrics** | 7 | `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate` |
-| **RAG** | 8 | `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index` |
-| **Data** | 3 | `data-yaml-get`, `data-json-get`, `data-csv-query` |
-| **Vault** | 11 | `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage` |
-| **Agent** | 8 | `agent-sessions/send/notify/dispatch`, `agent-register/profile/list/spawn` |
-| **Domain Map** | 2 | `domain-map-analyze`, `domain-map-view` |
-| **Workspace** | 4 | `workspace-info/list/update/link` |
-| **Environment** | 6 | `env-init/create/list/status/merge/delete` |
-| **Pipeline** | 10 | `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold` |
-| **Azure Sync** | 10 | `azure-sync-*`, `azure-pr-*` |
-| **Bootstrap** | 3 | `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands` |
-
-### 5 Hooks
-
-| Hook | Type | Description |
-|---|---|---|
-| **Context Compacting** | `experimental.session.compacting` | Injects session context when context window compacts |
-| **First-Run Guide** | `experimental.chat.system.transform` | Injects setup instructions on first session |
-| **Shell Environment** | `shell.env` | Injects JARVIS env vars into shell sessions |
-| **Guardrails** | `tool.execute.before` | Governance policy enforcement on tool invocations |
-| **Event Handlers** | `event` | Token usage tracking and cross-context event handling |
+### 115 Tools across 15 categories
+
+- **Context Memory** (8) — `context-session-*`, `context-todo-*`, `context-note-*`, `context-search`
+- **Kanban Cards** (12) — `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief`
+- **Kanban Board** (15) — `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check`
+- **Kanban Grooming** (4) — `kanban-grooming-validate`, `kanban-card-scope-doc/criteria/estimate`, `kanban-card-gate`
+- **Governance** (2) — `governance-validate`, `governance-policies`
+- **Token Metrics** (7) — `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate`
+- **RAG** (8) — `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index`
+- **Data** (3) — `data-yaml-get`, `data-json-get`, `data-csv-query`
+- **Vault** (11) — `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage`
+- **Agent** (8) — `agent-sessions/send/notify/dispatch`, `agent-register/profile/list/spawn`
+- **Domain Map** (2) — `domain-map-analyze`, `domain-map-view`
+- **Workspace** (4) — `workspace-info/list/update/link`
+- **Environment** (6) — `env-init/create/list/status/merge/delete`
+- **Pipeline** (10) — `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold`
+- **Azure Sync** (10) — `azure-sync-*`, `azure-pr-*`
+- **Bootstrap** (3) — `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands`
+
+### 8 Hooks
+
+- **Context Compacting** — Injects session context when context window compacts
+- **First-Run Guide** — Injects setup instructions on first session
+- **Shell Environment** — Injects JARVIS env vars into shell sessions
+- **Guardrails** — Governance policy enforcement on tool invocations
+- **Event Handlers** — Token usage tracking and cross-context event handling
+- **Execution Journal** — Crash recovery via tool execution state tracking
+- **Slash Commands** — `/healthcheck`, `/sync-azure`, `/start-card`, `/config`
+- **Config Command** — Agent-guided configuration editing
 
 ### 13 Governance Policies
 
 Runtime-enforced via `tool.execute.before` hook. Covers: CSV/YAML/env file access, force push protection, SQLite CLI blocking, destructive shell ops, credential file protection, and more.
 
+---
+
 ## Configuration
 
-All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults. Available sections:
+All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults:
 
 ```yaml
 # RAG embedding settings
@@ -267,32 +370,35 @@ pipeline:
 
 Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
 
+---
+
+## MCP Server Mode
+
+JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
+
+```bash
+bun run src/mcp-server.ts --directory /path/to/project
+```
+
+Configure tool filtering in `config/jarvis.yaml` under `mcp-server`.
+
+---
+
 ## Architecture
 
 ```
 jarvis-plugin/
   src/
-    domain/                  # Pure business logic, zero external deps
-      shared/                # WorkspaceId, EntityId, Result<T>
-      context-memory/        # Session, Todo, Note entities + services
-      kanban/                # Card state machine, Sprint, Epic, Grooming
-      governance/            # 13 policy rules, validation service
-      token-metrics/         # Token usage tracking, cost-per-card/sprint, budget alerts
-      rag/                   # RAG value objects, domain services
-      vault/                 # Vault document, section, table entities
-      domain-map/            # Bounded context detection, domain analysis
-      workspace-registry/    # Cross-project workspace registration
-      environment/           # Container-use environment management
-      agent-registry/        # Agent profile management
-      pipeline/              # CI/CD pipeline entities, gate enforcement
-      config/                # Configuration value objects + defaults
-    application/             # Use cases with DTOs (11 bounded contexts)
-    infrastructure/          # SQLite repos, Vectra, Ollama, FS adapters
-    tools/                   # 20 tool modules (113 tools total)
-    hooks/                   # 5 hooks (guardrails, compacting, first-run, events, shell-env)
-    tests/                   # 2,520+ tests across 85 test suites
-  obsidian-vault/            # Structured documentation
-  config/                    # jarvis.yaml configuration
+    domain/                  Pure business logic, zero external deps (11 bounded contexts)
+    application/             Use cases with DTOs
+    infrastructure/          SQLite repos, Vectra, Ollama, FS adapters
+    tools/                   20 tool modules (115 tools total)
+    hooks/                   8 hooks
+    tests/                   2,670+ tests across 93 test suites
+  scripts/setup/             Per-OS automated setup scripts
+  obsidian-vault/            Structured documentation
+  config/                    jarvis.yaml configuration
+  templates/                 AGENTS.md template engine
 ```
 
 **Key constraints:**
@@ -304,6 +410,8 @@ jarvis-plugin/
 - 11 bounded contexts with strict DDD boundaries
 - Production runtime: Bun (`bun:sqlite`); Tests: Node.js + Jest
 
+---
+
 ## Storage
 
 All data is stored locally:
@@ -313,30 +421,48 @@ All data is stored locally:
 - `.jarvis/rag/<workspace>/index-manifest.json` — File index registry (incremental indexing)
 - `~/.jarvis/registry.db` — Central workspace registry (cross-project)
 
-The `JARVIS_HOME` environment variable overrides `~/.jarvis/` default.
+The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
+
+---
 
-## Development
+## Local Development
 
 ```bash
+# Clone
+git clone <repo-url> jarvis-plugin
+cd jarvis-plugin
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
 # Run all tests
 npm test
 
 # Type check (zero errors required)
 npm run lint
 
-# Build
-npm run build
-
 # Single test file
 node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
 
 # Watch mode
 npm run dev
 
-# RAG index (standalone, bypasses MCP timeouts)
-npx tsx scripts/rag-index.ts --clear
+# Configure for local plugin development in OpenCode:
+# Add to your project's opencode.json:
+{
+  "plugin": {
+    "jarvis": {
+      "path": "/absolute/path/to/jarvis-plugin"
+    }
+  }
+}
 ```
 
+---
+
 ## Troubleshooting
 
 **Ollama connection refused**
@@ -352,10 +478,17 @@ npx tsx scripts/rag-index.ts --clear
 - Try full reindex: use `rag-index` tool with `clear: true`
 
 **Plugin not loading in OpenCode**
-- Verify `opencode.json` has `"plugin": ["@mc1global/opencode-jarvis"]`
+- Verify `opencode.json` exists in your project root (or globally at `~/.config/opencode/opencode.json`)
+- Verify it contains `"plugin": ["@mc1global/opencode-jarvis"]`
 - Check `~/.cache/opencode/node_modules/` for the installed package
 - Ensure Bun is installed (required for production runtime)
 
+**Windows: Plugin not loading**
+- JARVIS must run inside WSL, not native Windows PowerShell/cmd
+- Install prerequisites inside WSL using `setup-wsl.sh`
+- Run `opencode` from your WSL terminal
+- See [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl)
+
 **MCP server fails to start**
 - Ensure Bun is installed: `bun --version`
 - Run manually: `bun run src/mcp-server.ts --directory .`
@@ -365,30 +498,20 @@ npx tsx scripts/rag-index.ts --clear
 - Ensure Azure CLI is authenticated: `az login`
 - Test connectivity: use `azure-sync-config` tool
 
-**tsc errors in development**
-- Remember: `exactOptionalPropertyTypes` requires conditional spreading for optional props
-- Use `import type` for type-only imports (`verbatimModuleSyntax`)
-- Array indexing returns `T | undefined` (`noUncheckedIndexedAccess`)
+---
 
 ## Dependencies
 
-| Dependency | Purpose |
-|---|---|
-| `bun:sqlite` | Local SQLite database (production) |
-| `better-sqlite3` | SQLite for tests (Node.js) |
-| `js-yaml` | YAML file parsing |
-| `vectra` | Local vector store for RAG |
-| `ollama` | Embedding generation via local Ollama |
-| `@langchain/textsplitters` | Code-aware text chunking for RAG |
-| `@opencode-ai/plugin` | OpenCode plugin SDK (peer dependency) |
-| `@modelcontextprotocol/sdk` | MCP server protocol (optional) |
-
-## Test Coverage
-
-- **2,520+ tests** across 85 test suites
-- Domain, application, infrastructure, and tools layers tested
-- In-memory SQLite for fast, isolated integration tests
-- `tsc --noEmit` zero errors with all strict flags
+- `bun:sqlite` — Local SQLite database (production)
+- `better-sqlite3` — SQLite for tests (Node.js)
+- `js-yaml` — YAML file parsing
+- `vectra` — Local vector store for RAG
+- `ollama` — Embedding generation via local Ollama
+- `@langchain/textsplitters` — Code-aware text chunking for RAG
+- `@opencode-ai/plugin` — OpenCode plugin SDK (peer dependency)
+- `@modelcontextprotocol/sdk` — MCP server protocol (optional)
+
+---
 
 ## License
 

package/dist/application/azure-sync/push-use-cases.d.ts

@@ -45,7 +45,12 @@ export declare class AzureSyncUseCases {
     private pushEpics;
     private pushCards;
     private pushSprints;
-    /** Build a map of local sprint ID -> Azure iteration path. */
+    /**
+     * Build a map of local sprint ID -> Azure iteration path.
+     * Validates against actually existing iterations in Azure DevOps so that
+     * cards whose sprint failed to push are not assigned a non-existent path.
+     * This prevents Azure API errors from invalid iteration references (CD-022).
+     */
     private buildIterationPathMap;
     private pushSingleEntity;
     private linkToParentEpic;

package/dist/application/azure-sync/push-use-cases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"push-use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/azure-sync/push-use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sCAAsC,CAAC;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,kCAAkC,CAAC;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAOxG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,KAAK,EACV,eAAe,EAAE,gBAAgB,EACjC,WAAW,EAAE,YAAY,EACzB,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAC5D,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAIjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAID;;;GAGG;AACH,qBAAa,iBAAiB;IAKhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2C;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAEf,IAAI,EAAE,aAAa;IAUhD,wEAAwE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IA+DvE,yDAAyD;IACnD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IA4B3D,6DAA6D;IACvD,UAAU,CACd,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IA2CtC,iDAAiD;IAC3C,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;YAmB7C,SAAS;YA6CT,SAAS;YA4ET,WAAW;IA2DzB,8DAA8D;YAChD,qBAAqB;YAgBrB,gBAAgB;YA8DhB,gBAAgB;CAiB/B"}
+{"version":3,"file":"push-use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/azure-sync/push-use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sCAAsC,CAAC;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,kCAAkC,CAAC;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAOxG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,KAAK,EACV,eAAe,EAAE,gBAAgB,EACjC,WAAW,EAAE,YAAY,EACzB,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAC5D,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAIjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAID;;;GAGG;AACH,qBAAa,iBAAiB;IAKhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2C;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAEf,IAAI,EAAE,aAAa;IAUhD,wEAAwE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IA+DvE,yDAAyD;IACnD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IA+B3D,6DAA6D;IACvD,UAAU,CACd,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IA2CtC,iDAAiD;IAC3C,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;YAmB7C,SAAS;YA6CT,SAAS;YA4ET,WAAW;IA2DzB;;;;;OAKG;YACW,qBAAqB;YAqCrB,gBAAgB;YA8DhB,gBAAgB;CAiB/B"}