/ WARP.md
WARP.md
1 # WARP.md 2 3 This file provides guidance to WARP (warp.dev) when working with code in this repository. 4 5 ## Purpose and mental model 6 7 Sovereign OS is an operating system for cognitive offload: it turns your codebase, documents, and runtime signals (sessions, daemons, attention, economics) into a single living system. The center of gravity is the knowledge graph and the `sos` CLI; everything else feeds or reads from them. 8 9 When editing this repo as an agent, treat yourself as a system component obeying the same protocols as Claude/Gemini agents (see `AGENT_PROTOCOLS.md`). 10 11 --- 12 13 ## Environment & installation 14 15 Most core logic is Python; some subsystems use Node/Bun. 16 17 ### Python core 18 19 - Recommended local setup inside the repo root: 20 - Create and activate a virtualenv (optional but encouraged) 21 - Install Python dependencies: 22 ```bash 23 pip install -r requirements.txt 24 ``` 25 26 > Many modules assume a `~/.sovereign` directory for runtime state; most scripts will create it on demand. 27 28 ### Global Sovereign OS tooling (`sos` etc.) 29 30 For a first-time installation on a machine (see `AGENT_PROTOCOLS.md`): 31 32 ```bash 33 # From repo root 34 python3 scripts/install.py # bootstraps identity, PATH, hooks, etc. 35 36 # After reloading shell 37 sos # verify CLI works 38 sos start # begin a session 39 ``` 40 41 This installation step is mainly relevant for human operators; Warp can always invoke the CLI directly via `python3 scripts/sos.py` from the repo root. 42 43 ### Wallet (Lightning / Nostr) 44 45 The `wallet/` subproject is a Bun/TypeScript daemon that bridges Nostr identity, Lightning Address, and Cashu ecash (see `wallet/README.md`). To work on or run it locally: 46 47 ```bash 48 cd wallet 49 bun install 50 bun run start # start wallet daemon 51 bun run balance # query balance 52 ``` 53 54 Environment variables (optional overrides): `SOVEREIGN_DIR`, `NPC_GATEWAY`, `NSEC`. 55 56 --- 57 58 ## Core workflows & commands 59 60 ### Session lifecycle (mandatory for agents) 61 62 The universal agent protocols (`AGENT_PROTOCOLS.md`, `.cursorrules`) define a required session loop that all agents should honor: 63 64 1. **Bootstrap / start of session** 65 - Minimal, model-agnostic bootstrap: 66 ```bash 67 python3 scripts/agent_bootstrap.py 68 ``` 69 - If `sos` is available, the preferred entrypoint is: 70 ```bash 71 sos start 72 ``` 73 - This performs state checks (freshness of `sessions/LIVE-COMPRESSION.md`, daemon health, mesh checks, etc.) and may launch dashboards. 74 75 2. **During work** 76 - Maintain live state in `sessions/LIVE-COMPRESSION.md`. 77 - Keep FO state and other session artifacts in `sessions/` up to date when tools/scripts expect them. 78 79 3. **Close & shutdown** 80 - Extract and close the session: 81 ```bash 82 python3 scripts/session_close.py 83 ``` 84 - Archive and debrief (required before end-of-day): 85 ```bash 86 python3 scripts/end_of_day.py 87 ``` 88 - With `sos` installed, the operator equivalent is: 89 ```bash 90 sos end 91 ``` 92 93 > The “physics over policing” rules mean some operations (e.g., debrief) will hard-fail if there is uncommitted code or stale state. 94 95 ### Unified CLI: `sos` 96 97 The primary interface for interacting with Sovereign OS is the `sos` CLI defined in `scripts/sos.py`. From Warp, you can always invoke it as: 98 99 ```bash 100 python3 scripts/sos.py <subcommand> [...] 101 ``` 102 103 Key subcommands that matter for development and system health (see also `docs/OPERATORS-MANUAL.md`): 104 105 - **Quick status & nudges** 106 - `python3 scripts/sos.py` — banner + nudges (e.g., stale compression, uncommitted files, pending insights). 107 - `python3 scripts/sos.py status` — Git status, daemon health, and nudges in one place. 108 109 - **Session management** 110 - `python3 scripts/sos.py start` — wraps `agent_bootstrap.py`, checks physics, may open dashboards. 111 - `python3 scripts/sos.py end` — runs `session_report.py` and Night Watch (`night_watch.py`). 112 - `python3 scripts/sos.py archive [-q]` — archive current session (full or quick). 113 114 - **Search-before-build & theory-first hooks** 115 - **Search before adding new code** (mandatory protocol from `README.md` / `AGENT_PROTOCOLS.md`): 116 ```bash 117 python3 scripts/sos.py search "<concept>" 118 # or directly 119 python3 scripts/search_before_build.py "<concept>" 120 ``` 121 - **Theory-first analysis** for new conceptual work: 122 ```bash 123 python3 scripts/sos.py theory "<concept>" 124 # templates & docs/theory-first/README.md define the workflow 125 ``` 126 127 - **Graph & documentation operations** 128 - `python3 scripts/sos.py graph` — graph status via `scripts/graph_feeder.py`. 129 - `python3 scripts/sos.py graph health` — summary of nodes, edges, value, and orphans from `core.graph.sink`. 130 - `python3 scripts/sos.py docs health` — runs `scripts/doc_vitality.py` to score doc freshness and drift. 131 - `python3 scripts/sos.py docs stale|drift|orphans` — focused views over documentation issues. 132 133 - **Economics & value tracking** (hooked into `core.economics/*` and `core.markets/*`): 134 - `python3 scripts/sos.py done ...` — log completed work with risk‑adjusted V‑scores; writes to `sessions/FO-STATE.json` and integrates with anchors. 135 - `python3 scripts/sos.py anchor status|observe|triangulate` — multi‑anchor price system (BTC, wage, API, contractor, etc.). 136 - `python3 scripts/sos.py target ...` — target‑state economics (future‑back modeling of desired daily value). 137 - `python3 scripts/sos.py profile ...` — manage work profiles and prediction resolution. 138 - `python3 scripts/sos.py prefer ...` — explicit preference logging. 139 140 - **Immune system & safety** 141 - `python3 scripts/sos.py immune status|quarantine` — surfaces breaches and quarantined graph nodes using `core.principles.immune_system` and the graph store in `~/.sovereign/graph-data.json`. 142 - `python3 scripts/sos.py check ...` — value‑check system and optional Aesthetic Razor integration. 143 144 - **Deployment & daemons** 145 - `python3 scripts/sos.py deploy [status|health|restart]` — wraps `scripts/deploy_nodebox.py` to push daemon changes to the Nodebox environment. 146 - `python3 scripts/sos.py market [status|watch]` — use `scripts/market_monitor.py` to inspect markets & daemons. 147 148 ### Workspace launchers (Claude / Gemini) 149 150 These are primarily for human operators but important context for how the system is expected to be used (see `docs/OPERATORS-MANUAL.md`): 151 152 - `claude+` — bootstrap stack and launch Claude Code with dashboards and gardeners. 153 - `gemini+` — same idea but targeting Gemini Code, with configuration and API‑key management. 154 155 Under the hood these commands map onto the `sos claude` and Gemini scripts in `scripts/`, but from Warp it is usually sufficient to reason about and modify the Python/CLI layers rather than invoking GUI workspaces. 156 157 --- 158 159 ## Linting, checks, and tests 160 161 There is no single `pytest`/`tox` entrypoint; instead, the repo leans on custom health checks and targeted smoke tests. When changing core logic, prefer running the relevant scripts rather than inventing new ad‑hoc commands. 162 163 ### Code & protocol checks 164 165 - **Import and protocol sanity** 166 - `python3 scripts/check_imports.py` — import graph and dependency linting. 167 - `python3 scripts/protocol_enforcement.py` — enforces protocol invariants from `AGENT_PROTOCOLS.md` and docs under `docs/protocols/`. 168 169 - **Graph & gravity health** (for anything touching `core/graph`, `core/economics`, `core/metacog`): 170 - `python3 scripts/graph_integrity_check.py` 171 - `python3 scripts/gravity_check.py` 172 - `python3 scripts/gravity_lint.py` 173 174 - **Documentation vitality** 175 - `python3 scripts/doc_vitality.py` — overall doc freshness and drift report. 176 - `python3 scripts/doc_vitality.py --stale` — just stale docs. 177 - `python3 scripts/doc_vitality.py --orphans` — references without backing content. 178 - `python3 scripts/doc_dashboard.py [--watch]` — rich TUI documentation dashboard. 179 180 - **Observability & mesh** 181 - `python3 scripts/mesh_check.py` — mesh daemon & cross‑instance health. 182 - `python3 scripts/observability_check.py` — sanity check for metrics/logging surfaces. 183 184 ### Targeted test scripts 185 186 Use these when modifying the related subsystems: 187 188 - **Graph economics sanity** (`core.graph` + `core.markets.graph_economics`): 189 ```bash 190 python3 scripts/test_axiomatic_economics.py 191 ``` 192 193 - **Privacy scrubbing** (`core.nostr.privacy.PrivacyScrubber`): 194 ```bash 195 python3 scripts/test_privacy.py 196 ``` 197 198 These are designed as executable scripts with assertions and logging rather than a unified test runner. If you add new tests, follow the same pattern under `scripts/` unless a more formal test harness is introduced. 199 200 --- 201 202 ## High-level architecture 203 204 ### Big picture 205 206 At a high level, Sovereign OS is structured around a few key layers: 207 208 1. **CLI and scripts (`scripts/`)** — the operator-facing surface area (`sos`, bootstrap, daemons, dashboards, ingest/export tools). Almost all day‑to‑day operations are mediated through these scripts. 209 2. **Core subsystems (`core/`)** — long‑lived services and domain models (graph, markets, attention, metacognition, transport, identity, protocols, etc.). 210 3. **Runtime state (`~/.sovereign`, `sessions/`)** — durable graph store, daemon status, session‑level artifacts (LIVE‑COMPRESSION, FO state, synthesis, alerts). 211 4. **Knowledge and design (`docs/`)** — architecture, bedrock axioms, design principles, and theory‑first analyses that inform the implementation. 212 5. **Peripherals & integrations (`wallet/`, `integrations/`, `extensions/`)** — connect to Lightning, Nostr, Talon eye tracking, and other external systems. 213 214 ### Knowledge graph as the core boundary 215 216 The **knowledge graph** is the primary shared state across sessions and subsystems. Its main entrypoint is `core/graph/sink.py`: 217 218 - `GraphSink` is the *single ingest interface* for all graph sources: 219 - Attention daemon → aha moments and focus shifts. 220 - Session hooks → insights, decisions, compression events. 221 - Hunting parties and gardeners → discovered connections and orphan fixes. 222 - Mesh events → cross‑instance learnings. 223 - Manual additions and tooling. 224 - Responsibilities: 225 - Axiom detection and annotation (via `core.alignment.validity` and the axioms helpers). 226 - Content de‑duplication and node classification. 227 - Economic valuation of nodes/edges using `core.markets.graph_economics`. 228 - Writing graph snapshots to `~/.sovereign/graph-data.json` and publishing deltas (`mesh-delta.json`). 229 230 When touching any graph‑related code, keep in mind that: 231 232 - The graph is both **memory** and **economic terrain** (value flows through nodes and edges). 233 - Many higher‑level features (markets, immune system, mission control) assume invariants provided by `GraphSink`. 234 235 ### Metacognition and sessions 236 237 Cross‑session synthesis and awareness live primarily in `core/metacog` and `sessions/`: 238 239 - `core/metacog/mission_control.py` (Mission Control): 240 - Watches `sessions/` for LIVE‑COMPRESSION updates using `core.sync.file_watcher`. 241 - Detects *resonance* between threads (via `core.metacog.resonance`) and surfaces it as alerts and synthesis documents. 242 - Tracks **gravity wells** and topology by combining compression patterns with graph structure (`core.graph.gravity_topology`). 243 - Produces time‑bucketed synthesis outputs (`sessions/synthesis/{daily,weekly,...}`) and publishes events onto the mesh. 244 245 - `core/consciousness/*`: 246 - Implements First Officer / insight tracking (`insight_tracker.py`, `first_officer.py`). 247 - Exposes APIs used by `sos insight` for spaced repetition and Lindy‑style persistence. 248 249 - `sessions/` directory: 250 - `LIVE-COMPRESSION.md` — live compressed state of the current session; enforced as fresh by bootstrap scripts. 251 - `FO-STATE.json` — First Officer / session state consumed by `sos done` and other tools. 252 - `GARDENER_QUEUE.json`, `RESONANCE-ALERTS/`, `synthesis/*` — inputs to automated gardeners and night‑watch daemons. 253 254 ### Attention and real‑world signals 255 256 The attention system in `core/attention/` ties physical activity (eye tracking, apps, screens) back into the graph and session state: 257 258 - `core/attention/run_attention_system.py` is the unified launcher for the attention stack: 259 - Depends on Talon + Tobii for gaze, NSWorkspace for app focus, and optional camera head‑pose. 260 - Creates an integrated system (`create_integrated_system`) that routes attention events into orchestrators, membranes, and injectors. 261 - Feeds derived events and unified context back into sessions and eventually into the graph. 262 263 This layer is tightly coupled to macOS/Talon; when changing it, be mindful of its external assumptions and the check‑prerequisites logic. 264 265 ### Economics, markets, and value tracking 266 267 Economic primitives live mostly in `core/economics/` and `core/markets/` and are surfaced through `sos` commands: 268 269 - `core/economics/*` handles: 270 - Work profiles and curator skill (`work_profiles.py`). 271 - Multi‑anchor pricing (`anchors.py`). 272 - Target‑state modeling (`target_state.py`). 273 - Preference tracking (`preference_tracker.py`). 274 275 - `core/markets/*` adds market‑like structures on top of the graph: 276 - Prediction and decision markets (`prediction_market.py`, `decision_market.py`). 277 - Aesthetic/economic integration, including Hegelian integration of adversarial audits (`hegelian_integrator.py`). 278 - Moses attention & alignment drift monitors (`moses_attention.py`, `alignment_drift.py`). 279 280 These pieces are wired into CLI flows like `sos done`, `sos anchor`, `sos prefer`, `sos target`, `sos profile`, and `sos market audit`. 281 282 ### Mesh, transport, and external integrations 283 284 - **Mesh & transport** 285 - `core/mesh/*` — adapters to specific LLM providers (Claude, Gemini, Perplexity), unified mesh client, and model routing. 286 - `core/transport/*` — HTTP and internal routing layers used by daemons and Mission Control. 287 - `scripts/mesh_daemon.py` + `scripts/gardener_daemon.py` — long‑running daemons that host dashboards, perform gardening, and coordinate mesh state. 288 289 - **Identity & external rails** 290 - `core/identity/*` — identity management and key vaults. 291 - `core/nostr/*` — Nostr bootstrap, DVM client/provider, and privacy gates. 292 - `core/lightning/*` — Lightning/NWC client, wallet client, and `work_ledger` integration. 293 - `wallet/` — user‑facing Lightning Address/cashu wallet that writes to `~/.sovereign/work-ledger.json`, which Python core reads for unified accounting. 294 295 When you modify any daemon, mesh, or wallet code, you **must** consider deployment implications (see below). 296 297 --- 298 299 ## Protocols and constraints for Warp agents 300 301 Sovereign OS has explicit, code‑enforced protocols for all agents. Warp agents operating in this repo should inline these rules into their behavior. 302 303 ### Physics over policing 304 305 From `AGENT_PROTOCOLS.md` and `.cursorrules`: 306 307 - Git hooks block commits on syntax errors or unverified code. 308 - Bootstrap scripts emit warnings if LIVE‑COMPRESSION state is stale. 309 - Debrief/report scripts block when there is uncommitted code. 310 - New code **must** respect universal protocols; agent‑specific configs (e.g., CLAUDE.md, `.cursorrules`) are extensions, not replacements. 311 312 As a Warp agent: 313 314 - Prefer using existing enforcement scripts/hook installers instead of bypassing them. 315 - Do not introduce parallel, uncoordinated enforcement mechanisms; feed improvements back into the existing physics where possible. 316 317 ### Search‑before‑build & theory‑first 318 319 - Before creating new modules or major features, run the search‑before‑build script for the concept and reuse patterns when possible (`scripts/search_before_build.py`, `docs/theory-first/README.md`). 320 - For novel conceptual work, follow the theory‑first pattern: 321 - Extract theory → align with bedrock axioms → map to implementation → identify gaps → (if needed) escalate to Moses/First Officer. 322 323 Warp agents should: 324 325 - Prefer extending existing patterns (graph ingest, Mission Control, economics, protocols) over inventing parallel stacks. 326 - When asked to add a new capability, consider whether it should be wired into the knowledge graph, Mission Control, `sos` CLI, and/or protocols. 327 328 ### Axiomatic pushback 329 330 The Axiomatic Pushback Protocol (`docs/protocols/AXIOMATIC_PUSHBACK.md`) requires agents to challenge proposals that violate the bedrock axioms or established principles: 331 332 - If a requested change conflicts with A0–A4 or core principles, **do not silently comply**. 333 - Instead, explain which axiom/principle is in tension and propose either: 334 - a realignment of the implementation, or 335 - a conscious derivation of a new principle under `docs/` with appropriate graph mooring. 336 337 Warp agents should mirror this behavior by: 338 339 - Calling out when user requests would clearly break existing protocols (e.g., bypassing mesh/graph ingestion, disabling safety/immune checks, removing economic grounding), and 340 - Offering alternatives that keep the change aligned with principles. 341 342 ### Ship‑the‑fix and daemon deployment 343 344 From `AGENT_PROTOCOLS.md`: 345 346 - When you encounter structural issues (missing dependencies, stale checks, confusing flows), prefer *system‑level* fixes over per‑session workarounds. 347 - If you touch any of the daemon or core service entrypoints listed in `AGENT_PROTOCOLS.md` (e.g., `scripts/mesh_daemon.py`, `scripts/gardener_daemon.py`, `scripts/hypercore_daemon.js`, `run_mission_control.py`, `core/attention/daemon.py`), you must: 348 - Update the Nodebox deployment via `python3 scripts/deploy_nodebox.py` (usually through `sos deploy`). 349 - Ensure health checks pass (`sos deploy health`, `scripts/mesh_check.py`, `sos status`). 350 351 Warp agents should not assume deployment has happened automatically; if code changes affect daemons, surface deployment steps explicitly in responses. 352 353 --- 354 355 ## How to extend the system safely 356 357 When asked to implement new functionality in this repo, Warp agents should default to the following integration points instead of ad‑hoc scripts: 358 359 - **New long‑running behavior** → integrate into existing daemons (mesh, gardener, Mission Control, attention) or add a new daemon that is wired into the same deployment and health‑check flows. 360 - **New user‑facing operations** → expose via `scripts/sos.py` (or extend existing subcommands) rather than creating a separate top‑level script. 361 - **New knowledge structures or protocols** → add under `docs/` (architecture, principles, protocols, theory‑first) and hook into `scripts/doc_vitality.py` registries if needed. 362 - **New graph semantics** → extend `core.graph` (often via `GraphSink` or associated value/economics modules) so all subsystems benefit from the change. 363 364 Staying within these boundaries keeps Sovereign OS coherent and ensures that future Warp/Claude/Gemini agents operate over a consistent, principle‑aligned substrate.