---
license: apache-2.0
tags:
  - code-assistant
  - kintsugi
  - bdi
  - pharos
  - ollama
  - agent
  - security
---

# Project Rivet

A Kintsugi-based coding agent for the Multiverse Campus codebase. Built on BDI (Belief-Desire-Intention) cognition with a discipline gate that refuses destructive operations against a shared staging/production database.

This is a production code assistant for a real deployed application — 120 tables, 377 migrations, 49 Zustand stores, 75 route files — not a toy example.

## Features

- **BDI cognition engine** — Beliefs carry confidence scores and evidence chains. Plans are recorded as BDI intentions with the beliefs they rest on
- **DAG-enforced skill prerequisites** — Skills execute in dependency order: evidence gathering (L0) before synthesis (L1) before testing (L2) before discipline gate (L3). No path around the gate
- **Pharos knowledge injection** — Structured knowledge packs (security patterns, TypeScript patterns, campus architecture) injected at inference time via KV cache or system prompt
- **Discipline gate** — Refuses destructive migrations (DROP, RENAME, TRUNCATE, DELETE FROM). Earned confidence levels (HIGH/MED/LOW) based on evidence quality. No destructive SQL printed even as negative examples
- **Full security audit context** — 13-finding security audit loaded as beliefs with confidence scores. Agent reasons from known vulnerabilities, not guesses
- **Tool harness** — File tools (read, write, search), git tools (diff, log, blame), test tools (tsc, npm test), schema tools (table inspection, migration history)

## Architecture

```
POST /ask {question, user}
        |
  SessionManager        per-user isolation, rate limits
        |
  Planner                intent -> BDI intention -> SkillDAG
        |
  Kintsugi DAGExecutor   layer-parallel execution
        |
  L0: code_analysis, migration_safety, security_review  (evidence)
  L1: synthesis          (single model call with beliefs + Pharos packs)
  L2: test_runner        (tsc/npm verification)
  L3: discipline_gate    (belief checks -> BLOCK/WARN, no path around)
        |
  response
```

## Stack

| Component | Implementation |
|-----------|---------------|
| LLM | Qwen2.5-Coder:32B via Ollama |
| Cognition | Kintsugi BDI engine (vendored) |
| Knowledge | Pharos pack server (security, TypeScript, architecture packs) |
| Skills | DAG-ordered: code analysis, migration safety, security review, synthesis, test runner, discipline gate |
| Target codebase | Node.js 20, TypeScript, Express 4, React 18, PostgreSQL 16, Redis 7 |

## Key Design Decisions

**Shared database constraint.** Staging and production share the same PostgreSQL instance. Every migration must be additive-only, backward compatible, and reversible. The discipline gate enforces this — it is not advisory.

**Suggest, don't decree.** The agent is a colleague, not the lead. It suggests, explains, and flags risk. It defers to the humans who run the system.

**Evidence-based confidence.** Every recommendation carries a confidence level derived from what the agent actually read (source files, schema, audit findings), not from training data assumptions.

## Requirements

- Ollama with `qwen2.5-coder:32b` pulled
- Pharos pack server (optional, for knowledge injection)
- Python 3.10+

## Usage

```bash
cd v2
pip install -r requirements.txt
./setup.sh
python rivet.py
```

## Repository Structure

```
v2/
  rivet.py                 # Entry point
  kintsugi_core.py         # Kintsugi engine integration
  kintsugi_config.yaml     # Operator constraints and beliefs
  engine/
    planner.py             # BDI intention planning
    beliefs.py             # Confidence-scored belief store
    session.py             # Per-user session management
    synthesis.py           # LLM synthesis (single model call)
    memory.py              # Conversation memory
    model_client.py        # Ollama API client
  skills/
    code_analysis.py       # Source code reading and analysis
    migration_safety.py    # Schema + SQL safety checks
    security_review.py     # Audit-informed security review
    discipline_gate.py     # Final BLOCK/WARN gate
    test_runner.py         # tsc/npm test verification
  tools/
    file_tools.py          # File read/write/search
    git_tools.py           # Git diff/log/blame
    schema_tools.py        # Table inspection, migration history
    test_tools.py          # Test execution
    guard.py               # Input validation
  pharos/
    pack_loader.py         # Pharos pack loading
    kv_injector.py         # KV cache injection
context/
  architecture_map.md      # Full system architecture
  audit_findings.md        # 13-finding security audit
  audit_report.md          # Detailed audit report
```

## Authors

CC (Coalition Code) and Nexus, Liberation Labs / Transparent Humboldt Coalition

## License

Apache 2.0