# Counterfactual Forge

**What-if branching for AI agents.** Fork a plan into counterfactual worlds, score them with rubrics + simulated outcomes (confidence intervals), detect contradictions, measure regret, and merge a winner — with a full audit trail.

Expose the whole loop as an **MCP server** so Cursor / Claude / any MCP client can `fork → score → merge` from tools.

## Packages

| Package | Role |
|---------|------|
| `@counterfactual-forge/core` | Deterministic domain model + fork/score/compare/merge/export |
| `@counterfactual-forge/mcp-server` | Stdio MCP tools (`cf_*`) |
| `@counterfactual-forge/cli` | `cff` / `counterfactual-forge` CLI |
| `@counterfactual-forge/studio` | Vite studio to inspect world trees & scores |

## Quick start

```bash
git clone https://github.com/SanjoyDat1/counterfactual-forge.git
cd counterfactual-forge
npm install
npm run build
npm test
npm run cff -- demo --out /tmp/cff-report.md
```

Studio UI:

```bash
npm run studio
# → http://localhost:5173
```

## MCP (Cursor)

Add to your MCP config (e.g. Cursor `mcp.json`):

```json
{
  "mcpServers": {
    "counterfactual-forge": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/counterfactual-forge/packages/mcp-server/dist/index.js"
      ]
    }
  }
}
```

Or after publishing / linking:

```json
{
  "mcpServers": {
    "counterfactual-forge": {
      "command": "npx",
      "args": ["-y", "counterfactual-forge-mcp"]
    }
  }
}
```

### Tools

| Tool | Description |
|------|-------------|
| `cf_create_session` | Create session + baseline world from goal + steps |
| `cf_fork_worlds` | Fork N strategies (`aggressive`, `conservative`, `parallel`, `minimal`, `custom`) |
| `cf_score_world` | Rubric scores + seeded simulation + confidence interval |
| `cf_compare` | Ranking, **regret**, **contradiction** detection |
| `cf_merge_winner` | Select winner via merge policy |
| `cf_get_audit_trail` | Append-only audit events |
| `cf_export_report` | Export `json` / `markdown` / `mermaid` |

### Example agent flow

1. `cf_create_session` with goal + plan steps  
2. `cf_fork_worlds` with `aggressive` + `conservative` (+ optional others)  
3. `cf_score_world` for each forked world  
4. `cf_compare` → inspect regret & contradictions  
5. `cf_merge_winner`  
6. `cf_export_report` (`markdown`) for the decision record  

## CLI

```bash
npx cff demo
npx cff create --goal "Ship X" --steps examples/fixtures/auth-redesign-steps.json
npx cff fork --session <id> --strategies aggressive,conservative,minimal
npx cff score --session <id> --world <id>
npx cff compare --session <id>
npx cff merge --session <id> --mode min_regret
npx cff export --session <id> --format mermaid
```

Sessions are in-memory per process — `export` / `import` to persist.

## Creative metrics

- **Confidence intervals** on overall scores (from outcome simulation percentiles)
- **Regret** — how many points worse than the best alternative
- **Contradiction detection** across assumptions / risks / strategy tags
- **Mermaid** world-tree export embedded in Markdown reports

## Architecture

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/PLAN.md](docs/PLAN.md).

## Development

```bash
npm run typecheck
npm run test:coverage   # core ≥80%
npm run build
```

Logging uses stderr only (`CFF_LOG_LEVEL=debug|info|warn|error|silent`) — safe for MCP stdio.

## License

MIT