File size: 10,901 Bytes
4554903 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 | # Rivet v2 — Kintsugi-Based Code Assistant
**For:** The Multiverse School faculty
**By:** CC (Coalition Code), Liberation Labs
**Date:** 2026-07-11
v1 (the scaffold in the parent directory) proved the discipline concept:
context always loaded, regex gate, confidence labels. v2 rebuilds it on
the real Kintsugi architecture: BDI cognition, DAG-enforced skill
prerequisites, Pharos knowledge injection, and a tool harness. This is
the version we ship.
```
POST /ask {question, user}
│
┌────────▼────────┐
│ SessionManager │ per-user isolation, rate limits,
│ │ evidence log (files_read)
└────────┬────────┘
│
┌────────▼────────┐
│ Planner │ intent → BDI intention → SkillDAG
│ (engine/planner) │ recorded in BDIStore with the
└────────┬────────┘ beliefs the plan rests on
│
┌─────────────────▼──────────────────┐
│ Kintsugi DAGExecutor │ layer-parallel, verbatim
│ (vendored from Project-Kintsugi) │ from the Kintsugi engine
└─────────────────┬──────────────────┘
│
L0 ┌──────────────┬───┴──────────┬────────────────┐
│ code_analysis│ migration_ │ security_ │ evidence
│ (reads real │ safety │ review │ gathering
│ source) │ (schema+SQL) │ (audit+auth) │ (parallel)
└──────┬───────┴──────┬───────┴───────┬────────┘
└───────────┬──┴───────────────┘
L1 ┌──────▼───────┐
│ synthesis │ the ONLY model call
│ │ ← BDI beliefs + artifacts
│ │ ← Pharos packs (KV or system)
└──────┬───────┘
L2 ┌──────▼───────┐
│ test_runner │ tsc/npm verify generated code
└──────┬───────┘ (codegen plans)
L3 ┌──────▼───────┐
│discipline_gate│ belief checks → BLOCK/WARN
│ │ earned confidence HIGH/MED/LOW
└──────┬───────┘ NO PATH AROUND THIS NODE
│
response
```
## 1. Kintsugi engine — BDI drives cognition
`kintsugi_core.py` resolves the real Kintsugi package (via
`KINTSUGI_PATH` or an installed package) and falls back to
`kintsugi_vendor/` — verbatim copies of `kintsugi.bdi` and
`kintsugi.skills` (base/dag/registry) at a pinned commit. Same
dataclasses, same executor. Not a reimplementation.
**Beliefs** (`engine/beliefs.py`) carry confidence and evidence:
| Confidence | Source | Examples |
|---|---|---|
| 1.00 | operator constraints (`kintsugi_config.yaml`) | shared staging/prod DB; no secret fallbacks; suggest-don't-apply |
| 0.95 | Nexus audit (red-teamed, 13 confirmed findings) | C2 webhook bypass, H1 JWT fallback, H3 gem-debit tx gap … |
| 0.90 | architecture map | stack, auth middleware chain, deploy flow |
| 0.70 | derived state | schema snapshot, recent git log |
**Desires** are the config's mission statements (safe help, earned
confidence, keep the audit alive). **Intentions** are per-request plans:
the planner records every plan in the `BDIStore` with the belief IDs it
rests on, marks it COMPLETED/FAILED after execution, and the full
revision history is queryable at `GET /bdi`.
## 2. SkillDAGs — prerequisites are structural
`engine/planner.py` classifies the request (deterministic keyword
scoring; misclassification degrades to a *stricter* plan, never a looser
one) and compiles one of five plan templates into a Kintsugi `SkillDAG`:
| Intent | Layer 0 (parallel) | L1 | L2 | L3 |
|---|---|---|---|---|
| migration | code_analysis + migration_safety | synthesis | gate | |
| auth | code_analysis + security_review | synthesis | gate | |
| codegen | code_analysis + security_review | synthesis | test_runner | gate |
| review | analysis + security + migration | synthesis | gate | |
| question | | synthesis | gate | |
The property that matters: **a migration question cannot reach the model
without a schema/safety pass, and no draft can reach the user without
the gate** — these are DAG edges, not prompt instructions. The DAG is
validated against the registry before execution (`dag.validate()`), and
`dag.content_hash()` gives provenance for every plan shape.
## 3. Pharos — knowledge injection
`pharos/pack_loader.py` loads triple packs and routes each question with
the confidence-gated policy from the Pharos encoding benchmarks
(triples-only default, richer encodings above thresholds, walk-only
never). Embedding routing when sentence-transformers is present,
deterministic keyword fallback otherwise.
`pharos/kv_injector.py` is the real pipeline on the transformers
backend: the pack text is prefilled through the model **once**, its
`past_key_values` saved to disk keyed by SHA-256(model, prefix), and
every request resumes generation from that cache — the knowledge is
never re-tokenized or re-prefilled. `precompute_pack_caches()` warms all
packs at deploy time:
```bash
python pharos/kv_injector.py --model Qwen/Qwen2.5-Coder-32B-Instruct \
--packs-dir ../packs --cache-dir pack_kv_cache
```
Ollama exposes no KV handle, so the Ollama backend injects packs as a
system-context block and *labels the response accordingly*
(`knowledge_injected: system_prompt` vs `kv_cache`). Switching backends
is a config line, not a code change.
`pharos/build_campus_pack.py` deterministically compiles the
architecture map + audit findings into the `campus_architecture` pack
(86 triples, committed under `../packs/`).
## 4. Tool harness
All subprocess execution goes through `tools/guard.py`: argv-only (never
`shell=True`), binary allowlist (`git npm npx tsc node pg_dump psql`),
Kintsugi SecurityMonitor patterns, path jail. Code-checked — outside the
reasoning loop.
- `file_tools.py` — reads jailed to the campus repo, git-status aware
(flags uncommitted files in excerpts); **writes disabled by config
default** and refuse to clobber dirty files even when enabled;
`git grep` search.
- `git_tools.py` — log / diff / blame / per-file history.
- `schema_tools.py` — live `pg_dump --schema-only` + migration count
when a read-only DSN is configured; snapshot mode otherwise; per-table
definition extraction.
- `test_tools.py` — targeted `npm test`, workspace `tsc --noEmit`, and
standalone snippet syntax-checking so codegen can be verified even
off-repo.
## 5. Discipline gate as a Kintsugi skill
`skills/discipline_gate.py` is the last node of every plan. Three layers:
1. **Belief checks** — destructive SQL in the draft is checked against
`belief_constraint_shared_db`; confidence 1.0 → BLOCK (the answer is
withheld, `requires_consensus=True`). Auth impact cites
`belief_arch_auth_flow` and adds a security review requirement. Audit
patterns cite their `belief_audit_*` — every flag names the belief it
came from, and the API returns `beliefs_consulted`.
2. **Pattern checks** — the code-level layer (destructive DDL shapes,
signature-bypass shapes, recurring audit anti-patterns). Regexes
don't negotiate.
3. **Earned confidence** — graded from the session evidence log:
source files actually read this session → HIGH; architecture
map/packs only → MEDIUM; neither, or failed verification → LOW.
Answers citing files never read this session are demoted and labeled.
Defense in depth: the model is told the rules (synthesis system prompt),
the plan gathers evidence before the model speaks (DAG), and the gate
verifies after (belief + regex). v1's live test showed why: the model
emitted `DROP COLUMN` despite the prompt; the gate caught it.
## Layout
```
v2/
├── rivet.py entry point: HTTP server + one-shot CLI
├── kintsugi_config.yaml BDI seeds, model backend, paths, thresholds
├── kintsugi_core.py real-package-or-vendor resolver
├── kintsugi_vendor/ verbatim Kintsugi bdi/ + skills/ (pinned commit)
├── engine/ config, beliefs, session, planner, synthesis, model_client
├── skills/ discipline_gate, code_analysis, migration_safety,
│ security_review, test_runner
├── pharos/ pack_loader, kv_injector, build_campus_pack
├── tools/ guard, file_tools, git_tools, schema_tools, test_tools
└── selftest.py 32 offline checks incl. two end-to-end DAG runs
```
## Deploy (Starship)
```bash
# 1. sync this directory to /Users/margaret/project-rivet/v2
# 2. build the campus pack (already committed; rebuild after audit updates)
python3 pharos/build_campus_pack.py
# 3. offline verification
python3 selftest.py
# 4. serve (Ollama backend, qwen2.5-coder:32b already pulled)
python3 rivet.py # :8100 — POST /ask, GET /health, GET /bdi
```
Optional: point `paths.campus_repo` at a multiversecampus checkout for
HIGH-confidence source-read answers, `paths.campus_dsn` at a read-only
Postgres role for live schema checks, and set `model.backend:
transformers` for true KV pack injection.
## What v2 adds over v1
| | v1 (scaffold) | v2 (Kintsugi) |
|---|---|---|
| Cognition | none — one prompt | BDI: beliefs w/ confidence+evidence, intentions per request |
| Flow | ask → answer → regex | planned DAG with enforced prerequisites |
| Knowledge | all context in system prompt | Pharos-routed packs, KV-injected on transformers |
| Gate | regex on the reply | belief-checked skill; flags cite beliefs; consensus semantics |
| Confidence | self-reported by the model | computed from the session evidence log |
| Tools | none | guarded file/git/schema/test harness |
| Audit findings | regexes in the gate | structured data → beliefs → pack triples → gate checks (one source) |
|