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:

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)

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