# social-alignment

Future state projection and alignment for sovereign AI agents. The fifth pillar of the NSE platform. Part of the Humanjava ecosystem.

## Build & Test

```bash
pip install -e ".[dev]"
pytest -v
```

## Structure

- `src/social_alignment/` — package source
  - `types.py` — Lens, Severity, ActionDomain, Projection, Decision, SelfState, AlignmentConfig
  - `enclave.py` — AlignmentEnclave orchestrator (main entry point)
  - `lenses.py` — Five yellow line lens evaluators (builder, owner, partnership, defense, sovereign)
  - `selfstate.py` — SelfMonitor for agent health and degradation detection
  - `escalation.py` — EscalationDecision logic (none/inform/ask/halt)
  - `memory.py` — DecisionMemory, Pattern detection, WisdomReport generation
  - `storage.py` — MemoryStorage + FileStorage backends
- `tests/` — pytest suite
- `clawhub/` — OpenClaw skill metadata

## Conventions

- Python 3.10+, hatchling build, ruff linter (100 char line length)
- Zero external dependencies (stdlib only)
- The yellow line is a compass, not a rules engine — lenses evaluate futures, not enforce restrictions
- Five lenses: builder, owner, partnership, defense, sovereign — all five checked for every decision
- Severity levels: CLEAR → CAUTION → YIELD → STOP
- STOP always escalates to human — no exceptions, no timeouts
- YIELD escalates by default but is configurable
- SelfState flags detect degraded operation — under_influence and conflicting_signals force defer-to-human
- Decision memory stores WHY the agent chose, not just WHAT — this builds wisdom over time
- WisdomReports are generated every N decisions (configurable) and detect patterns
- Owner override rate is tracked — high override = misaligned calibration, not failure
- Novelty detection: if the agent hasn't done this type of thing before, lenses flag it for extra care
- `AlignmentConfig.owner_npub` ties to the Nostr identity — sovereignty starts with knowing who the human is
- Storage goes in config/, NEVER in workspace/ — the agent shouldn't be able to tamper with its own alignment state
