@neuroverseos/governance 0.8.0 → 0.9.0

package/AGENTS.md

@@ -4,6 +4,14 @@
 
 Runtime containment for AI agents. Define what an agent can and cannot do, then enforce it at every action. Deterministic — same event + same rules = same verdict. No LLM in the evaluation loop.
 
+> **Where the NeuroverseOS worldmodel lives.** The canonical Sovereign Conduit
+> worldmodel is at [github.com/NeuroverseOS/Worlds](https://github.com/NeuroverseOS/Worlds).
+> Every NeuroverseOS repo — including this one — auto-loads it via the
+> org-detect discovery tier. A reference sample sits at
+> `src/radiant/examples/neuroverse-base/` (alongside `src/radiant/examples/auki/`)
+> for developers who want to see the format. Do not edit the sample — edit the
+> source.
+
 ## Quick Start for Agents
 
 ### Install

package/README.md

@@ -22,28 +22,80 @@ Both ship in `@neuroverseos/governance`. Install once, use either or both.
 
 ## Radiant — behavioral intelligence for collaboration
 
-Radiant gives meaning to behavior. It reads activity (GitHub commits, PRs, reviews), classifies each event by who did it (human, AI, or both together), extracts behavioral signals, identifies patterns through AI interpretation governed by the worldmodel, and produces a structured read:
+Radiant gives meaning to behavior. It reads activity across every tool your team uses, classifies each event by who did it (human, AI, or both together), extracts behavioral signals, identifies patterns through AI interpretation governed by the worldmodel, and produces a structured read.
+
+### Five data sources, one pipeline
+
+| Source | What it reads | What it reveals |
+|---|---|---|
+| **GitHub** | Commits, PRs, reviews, comments | What was SHIPPED — architecture decisions, code quality, collaboration patterns |
+| **ExoCortex** | attention.md, goals.md, sprint.md | What was STATED — the gap between intent and action is drift |
+| **Discord** | Channel messages, threads, help requests | How the team COMMUNICATES — response times, newcomer welcome, unresolved debates |
+| **Slack** | Workspace messages, partner channels | How the team COORDINATES externally — client engagement, coalition alignment |
+| **Notion** | Page creation, updates, staleness | How the team DOCUMENTS — knowledge crystallization, doc gaps, decision records |
+
+All five produce `Event[]` → same pipeline → one read. One command, all sources:
+
+```bash
+npx @neuroverseos/governance radiant emergent aukilabs/ \
+  --lens auki-builder --worlds ./worlds/ --view team
+```
+
+### Three views for different scopes
 
 ```bash
-npx @neuroverseos/governance radiant emergent aukiverse/posemesh \
-  --lens auki-builder --worlds ./worlds/
+--view community    # public repos + public channels. Anyone can reproduce.
+--view team         # + private repos + team channels. Team exocortex.
+--view full         # + cross-exocortex comparison. Leader's view.
 ```
 
-Output:
+### Org-level reads
+
+Point at an entire GitHub org, not just one repo:
+
+```bash
+radiant emergent aukilabs/               # entire org
+radiant emergent aukilabs/exocortex      # single repo
+```
+
+### Output structure
 
 ```
 EMERGENT    — what patterns are visible in the team's work
-MEANING     — what it means against the worldmodel
+MEANING     — what it means against the worldmodel (plain English, no jargon)
 MOVE        — what to do about it (or "nothing's broken, keep shipping")
 ALIGNMENT   — L/C/N/R scores (human, AI, collaboration, composite)
 GOVERNANCE  — audit trail: which events triggered governance, on which side
 DEPTH       — what Radiant can see now vs what unlocks with more reads
 ```
 
-Three scores nobody else measures:
-- **L** — is the human's work aligned with the declared model?
-- **C** — is the AI's output aligned with the declared model?
-- **N** — when human and AI work together, is shared meaning preserved through the worldmodel? This score only exists because the worldmodel exists.
+### Three alignment scores nobody else measures
+
+- **L (Human work)** — is the human's activity aligned with the declared model? Not productivity — alignment.
+- **C (AI work)** — is the AI's output governed by the worldmodel? Right vocabulary? Invariants respected?
+- **N (Human–AI collaboration)** — when human and AI work together, is shared meaning preserved? This score only exists because the worldmodel provides a shared frame to measure against.
+
+### Memory + evolution
+
+Radiant writes each read to the ExoCortex as a dated Memory Palace file. Next run reads prior history, detects pattern persistence, and proposes worldmodel evolution — what to ADD (recurring candidate patterns) and what to REMOVE (invariants that haven't fired). A lean worldmodel with 5 sharp invariants is stronger than a bloated one with 20.
+
+### MCP server
+
+Configure Claude Code to call Radiant in conversation — no terminal needed:
+
+```json
+{
+  "mcpServers": {
+    "radiant": {
+      "command": "npx",
+      "args": ["@neuroverseos/governance", "radiant", "mcp",
+               "--worlds", "./worlds/", "--lens", "auki-builder"]
+    }
+  }
+}
+```
+
+Ask Claude: *"What's emerging in aukilabs/exocortex this week?"* — Claude calls `radiant_emergent` behind the scenes and responds conversationally.
 
 For the full Radiant documentation, see [`src/radiant/examples/auki/README.md`](src/radiant/examples/auki/README.md).
 
@@ -496,7 +548,7 @@ A World is a `.nv-world.md` file. It contains everything:
 | **Guards** | Domain-specific enforcement |
 | **Gates** | Viability classification |
 
-Three ways to create a world. All produce the same `WorldDefinition` object:
+Four ways to create a world. All produce the same `WorldDefinition` object:
 
 ```
 Path 1: Configurator (12 questions)
@@ -507,6 +559,9 @@ Path 2: CLI
 
 Path 3: Code
   defineWorld({...}) → WorldDefinition
+
+Path 4: World Model Builder (mission + skills + values + overlaps)
+  .worldmodel.md → neuroverse worldmodel build → .nv-world.md → WorldDefinition
 ```
 
 All three work with the same runtime. A world created through the configurator works identically to one written by hand.
@@ -695,6 +750,7 @@ const verdict = evaluatePlan({ intent: 'buy billboard ads' }, plan);
 | `neuroverse mcp` | MCP governance server |
 | `neuroverse plan` | Plan enforcement commands |
 | `neuroverse lens` | Manage behavioral lenses (list, preview, compile) |
+| `neuroverse worldmodel` | Behavioral world model builder (init, validate, build, explain) |
 
 ### Lens CLI
 
@@ -718,6 +774,120 @@ neuroverse lens compare --input "I'm stressed" --lenses stoic,coach,calm
 neuroverse lens add --world ./world/ --name "Support" --tagline "Patient and clear" --emotion warm
 ```
 
+### World Model CLI
+
+Build behavioral world models from mission, skills, values, and emergent overlap effects.
+
+A `.worldmodel.md` file defines three layers:
+
+1. **Core Model Geometry** — mission, domains (each carrying skills + values), overlap effects, center identity
+2. **Contextual Modifiers** — authority layers, spatial contexts, interpretation rules
+3. **Evolution Layer** — aligned/drift behaviors, signals, decision priorities, evolution conditions
+
+The compiler transforms this into executable governance artifacts:
+
+```bash
+# Scaffold a new behavioral model
+neuroverse worldmodel init --name "My Model"
+
+# Validate structure and completeness
+neuroverse worldmodel validate ./my-model.worldmodel.md
+
+# Human-readable model summary
+neuroverse worldmodel explain ./my-model.worldmodel.md
+
+# Compile to .nv-world.md + signals + overlaps + contexts + lenses
+neuroverse worldmodel build ./my-model.worldmodel.md --output ./world/
+
+# Emit individual artifacts
+neuroverse worldmodel emit-world ./my-model.worldmodel.md
+neuroverse worldmodel emit-signals ./my-model.worldmodel.md
+neuroverse worldmodel emit-lenses ./my-model.worldmodel.md
+neuroverse worldmodel emit-contexts ./my-model.worldmodel.md
+neuroverse worldmodel emit-overlaps ./my-model.worldmodel.md
+```
+
+Example `.worldmodel.md`:
+
+```markdown
+---
+name: Auki Vanguard
+version: 1.0.0
+---
+
+# Core Model Geometry
+
+## Mission
+Build the real world web while preserving long-term mission alignment.
+
+## Domains
+
+### Future Foresight
+#### Skills
+- Strategic Thinking
+- Systems Design
+#### Values
+- Long-term thinking
+- Intellectual honesty
+
+### Narrative Dynamics
+#### Skills
+- Storytelling
+- Communication Design
+#### Values
+- Authenticity
+- Clarity
+
+## Overlap Effects
+- Future Foresight + Narrative Dynamics = Inspiration
+
+## Center Identity
+Collective Vanguard Leader
+
+# Contextual Modifiers
+
+## Authority Layers
+- founder
+- contributor
+- agent
+
+## Spatial Contexts
+- strategy
+- execution
+- deployment
+
+## Interpretation Rules
+- ambiguity from a founder carries more system-wide risk than from a contributor
+
+# Evolution Layer
+
+## Aligned Behaviors
+- communicates future direction in ways others can act on
+
+## Drift Behaviors
+- mission language disconnected from execution
+
+## Signals
+- clarity
+- ownership
+- follow_through
+
+## Decision Priorities
+- long_term_ecosystem > short_term_convenience
+
+## Evolution Conditions
+- propose model updates when repeated behavior contradicts a current assumption
+```
+
+The deterministic compiler produces:
+- **`.nv-world.md`** — executable world file (thesis, invariants, state, rules, gates, outcomes, lenses)
+- **`signals.json`** — signal schema for behavioral tracking
+- **`overlaps.json`** — overlap map with pairwise domain effects and matrix view
+- **`contexts.json`** — contextual modifiers for interpretation shaping
+- **`lenses.json`** — lens suggestions derived from overlap effects
+
+Two bundled examples ship with the package: `auki-vanguard.worldmodel.md` and `neuroverse-governance.worldmodel.md`.
+
 ---
 
 ## Architecture