ivd

<p align="center">
  <strong>Intent-Verified Development (IVD)</strong><br>
  <em>A framework where AI writes the intent, implements against it, and verifies — so hallucinations are caught and turns drop to one.</em>
</p>

<p align="center">
  <a href="https://github.com/leocelis/ivd/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"></a>
  <a href="https://github.com/leocelis/ivd"><img src="https://img.shields.io/badge/version-3.1-blue?style=flat-square" alt="Version"></a>
  <a href="https://github.com/leocelis/ivd"><img src="https://img.shields.io/badge/python-3.12-blue?style=flat-square&logo=python&logoColor=white" alt="Python 3.12"></a>
  <a href="https://github.com/leocelis/ivd"><img src="https://img.shields.io/badge/MCP-compatible-purple?style=flat-square" alt="MCP Compatible"></a>
  <a href="https://github.com/leocelis/ivd/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/leocelis/ivd/ci.yml?branch=main&style=flat-square&label=tests" alt="Tests"></a>
</p>

<p align="center">
  <a href="https://ivdframework.dev"><strong>→ ivdframework.dev</strong></a> — full docs, hosted server, and access request
</p>

<p align="center">
  <strong>New here?</strong>
  Start with <a href="judgment_explained.md"><code>judgment_explained.md</code></a>
  — a 5-minute, plain-English on-ramp that explains what problem the
  Judgment phase solves and how, before you read the spec.
</p>

---

## The Problem

AI agents hallucinate not because they're bad — but because you're feeding the wrong knowledge system.

Research shows LLMs rely primarily on **contextual knowledge** (the prompt) over **parametric knowledge** (training data) — but only when the context is structured and precise ([Huang et al., ICLR 2024](https://openreview.net/forum?id=IVnodl8XR2); [9-LLM contextual vs. parametric study, 2024](https://arxiv.org/abs/2404.04838)). When you give vague prose — a PRD, a user story, a chat message — the context channel is underloaded. The model fills the gaps from training. Those gaps are the hallucinations.

```
Without IVD                              With IVD

You: "Add CSV export"                    You: "Add CSV export for compliance"
AI:  [builds with wrong columns]         AI:  [writes intent.yaml with constraints]
You: "No, these columns, ISO dates"      You:  "Yes, that's what I meant"
AI:  [rewrites, still wrong]             AI:  [implements, verifies against constraints]
You: "Still not right..."                You:  "Done. First try."
  Many turns. Many hallucinations.         One turn. Mismatches caught by the constraint check, not by you.
```

**IVD saturates the contextual channel** with structured, verifiable intent — so the model has nothing to guess.

---

## Quick Start

**Works locally. No API key required. Under 5 minutes.**

### 0. See it work first (30 seconds, no setup)

```bash
git clone https://github.com/leocelis/ivd.git && cd ivd
python3 examples/intent_demo/run_demo.py
```

Runs offline. Shows a vague prompt producing a hallucinated implementation, then
the same request run against a structured intent artifact — with the constraint
check catching the mismatch before you'd ever see it. This is the core loop this
README is about; everything below is how to wire it into your own agent.

### 1. Clone and setup

```bash
git clone https://github.com/leocelis/ivd.git
cd ivd
./mcp_server/devops/setup.sh    # creates .venv, installs all deps
```

### 2. Add to your IDE

**Important:** `command` must point at the **venv's** Python — `setup.sh` installs
IVD's dependencies into `.venv/`, not your system Python. Using `"command": "python"`
here will fail with `ModuleNotFoundError`. Replace `/path/to/ivd` with your actual
clone path.

**Cursor** (Settings → Features → MCP):

```json
{
  "servers": {
    "ivd": {
      "type": "stdio",
      "command": "/path/to/ivd/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/ivd"
    }
  }
}
```

**VS Code / GitHub Copilot** (`.vscode/mcp.json`):

```json
{
  "mcpServers": {
    "ivd": {
      "command": "/path/to/ivd/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/ivd"
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ivd": {
      "command": "/path/to/ivd/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/ivd"
    }
  }
}
```

> A `pyproject.toml` now ships in the repo (`pip install .` or `pip install -e .`
> gives you an `ivd-mcp` console command). A PyPI release (`uvx ivd-mcp`, no clone
> required) is planned — see [ROADMAP.md](ROADMAP.md).

### 3. Use it

Ask your AI agent to use IVD tools. For example:

- *"Use ivd_get_context to learn about the IVD framework"*
- *"Use ivd_scaffold to create an intent for my user authentication module"*
- *"Use ivd_validate to check my intent artifact"*

That's it. 32 of 33 tools work immediately with zero configuration — only `ivd_search` needs an `OPENAI_API_KEY`.

### 4. Enable semantic search (optional)

`ivd_search` requires embeddings. Generate them once (~$0.01, under a minute):

```bash
export OPENAI_API_KEY=your-key
./mcp_server/devops/embed.sh
```

---

## How It Works

```
1. You describe      →  what you want (natural language)
2. AI writes         →  structured intent artifact (YAML with constraints and tests)
3. You review        →  "Is this what I meant?" (clarification before code)
4. AI stress-tests   →  edge cases, gaps, assumptions, constraint conflicts
5. AI implements     →  constraint-segmented (group → implement → re-read → verify → next)
6. AI verifies       →  full sweep: does every constraint pass?
```

The key insight: clarification happens at the **intent stage**, not after code. The AI writes a verifiable contract, you approve it, then implementation is mechanical — and self-verifying.

---

## MCP Tools

33 tools available to any MCP-compatible AI agent (19 core + 10 Judgment tools (8 added in v3.0; `ivd_judgment_check_installed` and `ivd_judgment_resolve` added in v3.1) + 4 Canon tools added in v3.1):

### Core (19)

| Tool | What it does |
|------|-------------|
| `ivd_get_context` | Load framework principles, cookbook, or cheatsheet |
| `ivd_search` | Semantic search across all IVD knowledge |
| `ivd_validate` | Validate an intent artifact against IVD rules |
| `ivd_review_intent` | Rank constraints by risk before implementation (human review gate) |
| `ivd_run_constraint_tests` | Opt-in runner for allowlisted pytest nodes referenced by an intent |
| `ivd_attest` | Process-attestation gate — check the agent actually *followed* the method (segmentation, re-read, coverage, joint satisfaction), not just that the artifact is well-formed |
| `ivd_import_spec` | Parse a GitHub Spec Kit or OpenSpec `spec.md` into a constraint scaffold |
| `ivd_scaffold` | Generate a new intent artifact from a template |
| `ivd_init` | Initialize IVD in an existing project |
| `ivd_assess_coverage` | Scan a project and report intent coverage |
| `ivd_load_recipe` | Load a specific recipe pattern |
| `ivd_list_recipes` | Browse all available recipes |
| `ivd_load_template` | Load an intent or recipe template |
| `ivd_find_artifacts` | Discover intent artifacts in a project |
| `ivd_check_placement` | Verify artifact naming and placement |
| `ivd_list_features` | Derive feature inventory from intent metadata |
| `ivd_propose_inversions` | Generate inversion opportunities |
| `ivd_discover_goal` | Help users who don't know what to ask |
| `ivd_teach_concept` | Explain concepts before writing intent |

### Judgment Phase (10) *— dormant unless `<project_root>/.judgment/` exists*

> **New to Judgment?** Read [`judgment_explained.md`](judgment_explained.md) first
> — plain-English "what problem it solves and how" in 5 minutes — then the tool
> table below and the runnable showcase further down will make immediate sense.

| Tool | What it does |
|------|-------------|
| `ivd_judgment_init` | Bootstrap `.judgment/` folder + per-domain baselines |
| `ivd_judgment_capture` | Write a raw correction ledger entry (< 30s) |
| `ivd_judgment_codify` | Return a structured codify prompt for the agent |
| `ivd_judgment_save_codified` | Persist the agent's filled codify fields |
| `ivd_judgment_pair` | Capture a comparison_pair (Pearl Rung-1 alternative to A/B) |
| `ivd_judgment_detect_patterns` | Cluster ledger entries into patterns |
| `ivd_judgment_inject_context` | Prioritized judgment context for downstream agents |
| `ivd_judgment_propose_recommendation` | Draft recommendation against a pattern (with `build/buy/hire/partner` sub-types) |
| `ivd_judgment_resolve` | Close the loop: record an entry's resolution (outcome, whether it held) and move it `codified\|paired → resolved`, so future runs don't re-derive a settled diagnosis. (v3.1) |
| `ivd_judgment_check_installed` | Detect whether `<project_root>/.judgment/` exists. **Never writes to disk** — returns the ready-to-call init payload the agent must offer to the user with explicit permission. (v3.1) |

**Architecture (v3.1):** substance lives in the [`ivd/judgment/`](judgment/) engine package (typed `@dataclass` schemas; `engine_version` + reproducible SHA-256 hash on `Pattern` and `InjectionResult` for diffability and audit). `mcp_server/tools/judgment.py` is a thin facade that dispatches to the engine. Mirrors the Canon (Phase 0) architecture for symmetry. Server-level kill switch: `IVD_JUDGMENT_TOOLS_ENABLED=false`.

**See it work.** A runnable showcase walks through the full Judgment loop end-to-end — capture three real-world AI corrections, codify them, promote a Pattern, and watch the same LLM (`gpt-4o-mini`, temperature=0) generate **different** code on the same request after the Pattern enters its system message. No trust required — run it, read the terminal.

```bash
# From the ivd/ directory