# CVC — Workspace Instructions

## Project Overview

CVC (Cognitive Version Control) is "Git for AI context" — a Merkle DAG-based versioning system that captures agent reasoning as immutable cognitive commits. Published as `tm-ai` on PyPI. See [CVC.md](../CVC.md) for full tech stack, conventions, and directory map.

## Build & Test

```bash
pip install -e ".[all,dev]"   # Dev install with all LLM providers
ruff check . && ruff format .  # Lint + format (100-char line limit)
pytest                          # Async tests (asyncio_mode="auto")
hatch build                     # Build wheel + sdist
```

## Code Style

- **Python 3.11+**, async-first (`aiosqlite`, `httpx`, `pytest-asyncio`)
- **Pydantic V2** models for all data structures — never use V1 patterns (`class Config`, `.dict()`)
- **Type hints** on every function signature
- **Imports**: `from __future__ import annotations` → stdlib → third-party → local
- **Ruff** enforces rules `E, F, I, W` at 100-char max — no manual formatting needed

## Architecture

Three-tier storage per workspace (`.cvc/` directory):
1. **SQLite** (`.cvc/cvc.db`) — commit graph, branches, metadata
2. **CAS** (`.cvc/objects/`) — zstandard-compressed context blobs, addressed by SHA-256
3. **ChromaDB** — semantic vector embeddings for knowledge search

Key packages:
| Package | Responsibility |
|---------|---------------|
| `cvc/core/` | Pydantic models, SQLite index, Merkle hashing |
| `cvc/operations/` | CVCEngine: commit, branch, merge, restore |
| `cvc/agent/` | Chat REPL, LLM calls, 5 specialized sub-agents |
| `cvc/adapters/` | LLM provider abstraction (Anthropic, OpenAI, Google, Ollama) |
| `cvc/mcp_server.py` | MCP protocol server for IDE integration |
| `cvc/gateway.py` | FastAPI dashboard (port 17888) |
| `cvc/proxy.py` | HTTP middleware, intercepts LLM requests |
| `cvc-node/` | TypeScript/Bun companion — mirrors Python architecture |

## Critical Gotchas

- **Merkle DAG is immutable** — no rebase/squash. Changing an ancestor invalidates all descendants.
- **Three-tier write order** — blob → SQLite → ChromaDB, always in sequence. Partial writes create orphans.
- **Semantic merge uses LLM** — merge conflict resolution calls an LLM; fails if API is unreachable.
- **Firebase auth is placeholder** — `cvc/auth.py` needs real project config before production use.
- **Workspace detection walks up** — MCP server auto-detects workspace by walking parent dirs for `.cvc/`, `.git/`, `pyproject.toml`. Use `cvc_set_workspace` or `CVC_WORKSPACE` env var to override.
- **Sub-agent capability tiers** — Security agent cannot call external APIs; respect scoping in `cvc/agent/`.

## Testing Conventions

- All tests in `tests/`, async by default (`@pytest.mark.asyncio` auto-applied)
- Test names: `test_<feature>_<behavior>` pattern
- Use in-memory SQLite or tmp dirs — never touch real `.cvc/` state

## Documentation

Reference docs are in `docs/` — link to them, don't duplicate:
- [docs/CLI_AGENT_GUIDE.md](../docs/CLI_AGENT_GUIDE.md) — CLI usage and agent interaction
- [docs/MCP_DOCUMENTATION.md](../docs/MCP_DOCUMENTATION.md) — MCP server setup for IDEs
- [docs/CVC_TOOLS_REFERENCE.md](../docs/CVC_TOOLS_REFERENCE.md) — Tool/operation reference
- [docs/CHANGELOG.md](../docs/CHANGELOG.md) — Release history
