v2/ARCHITECTURE.md

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