| --- |
| 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 |
|
|
