Clean up nested duplicate: v2/v2/ARCHITECTURE.md

v2/v2/ARCHITECTURE.md

@@ -1,210 +0,0 @@
-# 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) |