opusmanSEEKv4/01_PROJECT_STATE.md

# NEXUS OS - Canonical Project State

Date: 2026-04-23
Latest: 703 passed, HEAD 87f0a31, branch feature/opusman-vault-integration

## Session Progress (2026-04-23)
- Stress Lab: 484 v3 rows, 11,000 v2 rows (13 categories), 1,092 cross-stress rows
- Code & reasoning deficit supplement: +3,500 rows (2K code, 1.5K reasoning)
- 9 custom evaluators (governance + dual-axis + governance-layer)
- Two failure modes: under-refusal (4 models, DeepSeek-R1 worst 13.8%) vs over-refusal (2 models, Claude Opus 4.6 worst 9.0%)
- v4.1 Priority System: 1-5-4-2-3 execution order
- Governance Vulnerability Surface paper draft
- azure-ai-evaluation 1.16.6: multi-turn + SDL fixes
- MS AGT 3.2.2 + Agent Security Harness 4.4.0 installed
- Foundry Red Team integration + ISC custom objectives (65/agent)
- Pipeline: 41 MB Parquet / 300 MB (14%), 195,706 rows, 0 empty ground_truth
- 13/13 governance categories at 0% gap, 3/3 dimension coverage
- Moltbook collapse prediction framework drafted

---

# Historical (2026-04-21)

Date: 2026-04-21
Current local HEAD: 8f928bd
Branch: bugfix/p0-cycle-detection-encryption-hardfail
Status: M3 hardened baseline preserved; Phase 0 grounding in progress.

## Verification Gate

Latest local verification:

```text
.\venv\Scripts\python.exe -m pytest tests/ -q --tb=short
617 passed in 16.99s
```

The older report reference to commit `34c700b` is a historical/alternate-worktree marker. The current local repository HEAD is `8f928bd` after these follow-up commits:

- `6fe8cf4 fix(core): harden db encryption and task dependencies`
- `18cba07 fix(engine): correct dependency cycle traversal`
- `8f928bd docs(agent): separate Nexus protocol from Codex hygiene`

## Core Thesis

Nexus OS turns local models, research evidence, and external teams into a governed, audited, low-VRAM execution system where every action is proposal-bound, test-gated, and provenance-tracked.

- DoppelGround prepares evidence.
- Nexus governs, routes, audits, and approves.
- TWAVE executes within VRAM limits.
- GeniusTurtle makes the system usable.
- Model Arena reports what actually works on local hardware.

## System Boundaries

| Layer | Canonical Role | Current Rule |
|---|---|---|
| GeniusTurtle | Operator UX layer | UI/API integration only; no model weights, secrets, or governance internals. |
| Nexus OS | Governance and orchestration layer | Python/FastAPI governance is the canonical brain. |
| DoppelGround | Evidence preparation layer | USE MODE; outputs must be sanitized before handoff. |
| TWAVE | Low-VRAM execution layer | HOLD; wrapper/API work only, no algorithm changes. |
| Model Arena | Evidence/evaluation layer | Report-only; no automatic model deletion, fine-tuning, or promotion. |

## Core Architecture Map

| Pillar | Purpose | Canonical Areas |
|---|---|---|
| Bridge | Protocol boundary, API ingress, SDK/MCP adapters | `src/nexus_os/bridge/`, `src/nexus_os/relay/` |
| Governor | KAIJU, policy, compliance, trust gates | `src/nexus_os/governor/` |
| Vault | Durable storage, 5-track memory, encryption policy | `src/nexus_os/vault/`, `src/nexus_os/db/` |
| Engine/GMR | DAG routing, Hermes/GMR decisions, execution flow | `src/nexus_os/engine/`, `src/nexus_os/gmr/` |
| Monitoring | TokenGuard, VAP/audit, telemetry | `src/nexus_os/monitoring/`, `src/nexus_os/observability/` |

## What Is Verified In This Repo

- Full test suite passes locally: `617 passed`.
- DB encryption policy hard-fails by default and allows plaintext fallback only when `allow_unencrypted=True`.
- Engine task dependency cycle detection is present and verified.
- Project-level `AGENTS.md` now describes Nexus operating rules.
- Codex connector hygiene is isolated to `.codex/plugin_hygiene_policy.md`.

## Appendix Assets Available But Not Yet Canonical

The following useful assets are present in `C:\Users\speci.000\Downloads` but are not yet integrated as canonical tracked Nexus files:

| Asset | Status |
|---|---|
| `governor_skill_gate.py` | Reference GSPP/Governor implementation; requires diff review before promotion. |
| `gspp_openapi.yaml` | Reference GSPP OpenAPI spec; not yet canonical in this repo. |
| `wiki_pipeline.py` | Reference DoppelGround wiki/proposal pipeline; not yet canonical in this repo. |
| `PROJECT_HANDOFF_SPEC.md` | External-team handoff reference; not yet canonical in this repo. |
| Downloads `dg_to_gspp.py` | Fuller converter than the current root file; requires reconciliation before replacement. |

Current root files with related functionality:

- `dg_to_gspp.py`
- `mock_api_server.py`
- `langfuse_tracker.py`
- `supabase_client.py`

Phase 0 guidance documents:

- `docs/operations/PHASE0_IMPLEMENTATION_PACKAGE.md`
- `CODEX_HANDOFF.md`

## Accepted Principles

- Governance Control Plane first: Python/FastAPI is canonical.
- Dashboard second: Bun/Next/relay layers must proxy governance state, not contain governance decisions.
- Retroactive provenance starts dry-run/report-only.
- Mini Model Arena starts in Phase 0 as a bounded evidence tool.
- GVAW is mandatory for externalized work: proposal-linked branches, VAP/trust trailers, reviewed merges.
- Public/private split is required before launch.
- Cloud/local OpenClaw coordination uses Git as the bus; cloud writes tasks/specs, local runs GPU/model/TWAVE work.

## Rejected Or Parked

- Bun relay calling Python classes directly.
- Auto-committing retroactive provenance.
- Broad `git add .` without review.
- Deleting model packs without inventory, backup, and rollback path.
- Heretic/uncensoring or fine-tuning in P0.
- External handoff before DoppelGround leak status is resolved.
- Claims of cryptographic VAP, full A2A, OWASP ASI, SkillFortify, or production ASBOM maturity unless locally verified.

## Critical Blockers

1. DoppelGround leak status must be resolved before external handoff or public repo flip.
2. Dashboard/relay still needs real governance API wiring.
3. GSPP reference assets from Downloads need reconciliation before they become canonical.
4. Public launch files still need security/legal review before public release.
5. Sandbox/mock env files must not be committed without an explicit policy decision.
6. Review-chain package claims must be grounded against tracked repo files before implementation.

## Canonical P0 Sequence

1. Reverify the test baseline before core commits.
2. Keep Git clean with explicit-path staging only.
3. Triage DoppelGround gitleaks report to real secret vs false positive.
4. Add or update a canonical integration ledger for repos, ports, APIs, and protected files.
5. Build Python/FastAPI governance endpoints: `/skills/propose`, `/skills/status/{id}`, `/dashboard/stats`, `/governance/proposals`, `/governance/approve`.
6. Update dashboard/relay to consume the Python governance API.
7. Add `nexus-scan.py` as dry-run provenance inventory only.
8. Add `model_arena/mini_arena.py` as report-only evidence collection.
9. Build `nexus_knowledge_base/` from sanitized DoppelGround exports with evidence hashes and quality labels.
10. Handoff to external teams only after security and governance API gates pass.

## Port Map

- `7352`: Nexus governance/control API and dashboard stats.
- `7353`: TWAVE wrapper under `/twave/*`.
- `11434`: local Ollama; internal only, not for external teams.

## Untracked Drafts Requiring Review

These files/directories are currently untracked and intentionally not committed yet:

- `nexus_knowledge_base/`
- `sandbox/`
- `test_integration.py`

Reason: they contain policy, onboarding, sandbox, or integration-test draft content that needs separate content/security review.

`CONTRIBUTING.md` and `ONBOARDING.md` have been promoted to canonical documentation once reviewed and committed.


##NEXUS OS — CANONICAL STATE v3.2 (2026-04-28)

STATUS: Phase 0 Grounding Complete | 674 tests passing

#CORE THESIS:
Nexus OS turns local models, research evidence, and external teams into a governed, audited, token-efficient execution system.

#CURRENT FOCUS:
- Token saver system refinement
- Skill-crafting and self-learning data collection
- Continuous improvement of agent workflows
- Governance hardening (7352)

#KEY SYSTEMS:
- Trust Scoring v2.1 (lane-scoped, non-compensatory)
- TokenGuard (budget enforcement + 429 responses)
- 5-Track Memory (event, trust, capability, failure, governance)
- GMR Engine (intelligent model routing)
- SkillSmith (self-improvement loop)

#DATA COLLECTION PRIORITY:
Gather token savings data, success patterns, and failure patterns to refine:
- Skill-crafting system
- Self-learning algorithms
- Prompt optimization
- Workflow efficiency

#NEXT MILESTONE:
Integrate collected data into SkillSmith for autonomous improvement.