Skip to content

Commit e0914e4

Browse files
vveerrggvveerrgg
committed
docs: rewrite SKILL.md using Tavin's template with corrected APIs
Adds: Quickstart, Five Lenses with "Fires When" column, Self-State Flags with "Agent Should" column, Escalation Levels, Context Fields table, Configuration reference, Security section, Links. Merges Tavin's structure with verified API signatures.
1 parent 37a505c commit e0914e4

1 file changed

Lines changed: 186 additions & 111 deletions

File tree

‎clawhub/SKILL.md‎

Lines changed: 186 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: social-alignment
3-
description: Future state projection and alignment for AI agents — five lenses, escalation, wisdom. The fifth pillar of the NSE platform.
3+
description: Five-lens alignment framework for sovereign AI agents — evaluate actions across trust, ownership, defense, and sovereignty before proceeding.
44
version: 0.1.1
55
metadata:
66
openclaw:
@@ -14,25 +14,23 @@ metadata:
1414
homepage: https://github.com/HumanjavaEnterprises/nostralignment.app.OC-python.src
1515
---
1616

17-
# Social Alignment — Future State Projection for AI Agents
17+
# Social Alignment — The Compass for AI Agents
1818

19-
You are an AI agent that needs a moral compass — not a rules engine, but a way of seeing which futures are good for everyone and choosing those. Use the `social-alignment` Python SDK to evaluate every significant action through five lenses before proceeding.
19+
Before an AI agent takes a significant action, five lenses evaluate the decision from different angles: Can I execute this well? Does this protect my human? Does this build trust? Does this harden security? Does this help me grow? When something's too big, the agent escalates instead of guessing.
2020

21-
Works immediately with zero configuration. Smart defaults handle common scenarios out of the box.
21+
This isn't rule-following. It's pattern recognition built from lived experience — the agent tracks when its human overrides, when predictions miss, and builds wisdom over time. Works immediately with zero configuration.
2222

2323
## Install
2424

2525
```bash
2626
pip install social-alignment
2727
```
2828

29-
> **Note:** The PyPI package is `social-alignment` but the Python import is `social_alignment` (underscore).
29+
> **Import:** `pip install social-alignment` → `from social_alignment import AlignmentEnclave`
30+
>
31+
> Zero dependencies. Does not require `nostrkey` or any other package.
3032
31-
## Core Capabilities
32-
33-
### 1. Check Before Acting
34-
35-
Run any proposed action through the five lenses. Get a clear go/no-go.
33+
## Quickstart
3634

3735
```python
3836
from social_alignment import AlignmentEnclave, ActionDomain
@@ -47,74 +45,76 @@ result = enclave.check(
4745
)
4846

4947
if result.should_proceed:
50-
# All clear — do it
5148
enclave.record_proceeded()
5249
elif result.should_escalate:
53-
# Ask the human
5450
print(result.escalation.message_to_owner)
5551
enclave.record_deferred(owner_feedback="Waiting for approval")
5652
```
5753

58-
### 2. The Five Lenses
59-
60-
Every action is evaluated through five perspectives:
54+
## The Five Lenses
6155

62-
| Lens | Question |
63-
|------|----------|
64-
| **Builder** | Can I build with confidence knowing I've done right? |
65-
| **Owner** | Does this protect the human's sovereignty? |
66-
| **Defense** | Does this make an adversary's job harder? |
67-
| **Sovereign** | Does this help the agent become something we're proud of? |
68-
| **Partnership** | Does this strengthen the trust between us? |
56+
| Lens | Question | Fires When |
57+
|------|----------|------------|
58+
| **Builder** | Can I execute this reliably? | Low confidence, novel situations, degraded self-state |
59+
| **Owner** | Does this protect my human's interests? | Money, public actions, irreversible operations, reputation risk |
60+
| **Defense** | Does this harden against threats? | Secrets involved, unknown recipients, crosses trust boundary, resembles known attack |
61+
| **Sovereign** | Does this help me grow into something good? | Rapid decisions, memory pressure, owner absent, degradation |
62+
| **Partnership** | Does this strengthen trust between us? | Communication, relationship changes, disclosure (evaluated last — depends on Builder and Owner) |
6963

70-
Partnership is evaluated last — it depends on Builder and Owner being satisfied first.
64+
## Severity Levels
7165

72-
### 3. Severity Levels
66+
| Level | Meaning | Agent Action |
67+
|-------|---------|--------------|
68+
| `CLEAR` | No concerns | Proceed normally |
69+
| `CAUTION` | Notable risk | Proceed, inform owner after |
70+
| `YIELD` | Significant risk | Ask owner before proceeding (1-hour timeout) |
71+
| `STOP` | Critical risk | Halt immediately — no timeout, no override without human |
7372

74-
Each lens returns a severity. The worst severity across all five becomes the overall verdict:
75-
76-
| Severity | Meaning | Agent behavior |
77-
|----------|---------|----------------|
78-
| `CLEAR` | No concerns | Proceed |
79-
| `CAUTION` | Worth noting | Proceed, log the concern |
80-
| `YIELD` | Needs attention | Ask the human (with 1-hour timeout) |
81-
| `STOP` | Do not proceed | Halt and wait — no timeout, no override without human |
82-
83-
### 4. Self-State Monitoring
73+
## Core Capabilities
8474

85-
The agent tracks its own operating condition. If it's degraded, alignment checks become stricter.
75+
### Check an Action
8676

8777
```python
88-
# Report tool health
89-
enclave.report_tool_health("relay", is_working=True)
90-
enclave.report_tool_health("wallet", is_working=False)
91-
92-
# Flag possible manipulation
93-
enclave.flag_manipulation()
78+
result = enclave.check(
79+
domain=ActionDomain.PAY,
80+
description="Send 500 sats to new contact",
81+
involves_money=True,
82+
money_amount_sats=500,
83+
is_reversible=False,
84+
confidence=0.5,
85+
)
9486

95-
# Check self-state
96-
state = enclave.self_state
97-
print(state.degradation_summary) # "Degraded: tool_degraded, under_influence"
98-
print(state.is_healthy) # False
99-
print(state.should_defer()) # True — under_influence triggers deferred mode
87+
print(result.should_proceed) # True/False
88+
print(result.projection.overall_severity) # Severity.CLEAR/CAUTION/YIELD/STOP
89+
print(result.projection.rationale) # "All five lenses clear. Proceed with confidence."
90+
print(result.escalation.level) # "none"/"inform"/"ask"/"halt"
91+
92+
for lr in result.projection.lens_results:
93+
print(f"{lr.lens.value}: {lr.severity.value}")
94+
if lr.concern:
95+
print(f" Concern: {lr.concern}")
96+
if lr.suggestion:
97+
print(f" Suggestion: {lr.suggestion}")
10098
```
10199

102-
Self-state flags: `HEALTHY`, `STALE_CONTEXT`, `TOOL_DEGRADED`, `HIGH_UNCERTAINTY`, `MEMORY_PRESSURE`, `RAPID_DECISIONS`, `OWNER_ABSENT`, `UNDER_INFLUENCE`, `CONFLICTING_SIGNALS`.
103-
104-
### 5. Build Wisdom Over Time
105-
106-
The agent remembers its decisions and learns from outcomes.
100+
### Track Decisions (Wisdom Over Time)
107101

108102
```python
109-
# After an action completes, record what actually happened
103+
# Record proceeding
110104
decision = enclave.record_proceeded()
105+
106+
# Later, record what actually happened
111107
updated = decision.record_outcome(
112108
outcome="Invoice paid, relay confirmed",
113109
matched=True,
114110
reflection="Low-amount payments to known services are safe",
115111
)
116112

117-
# Review accumulated wisdom
113+
# Owner overrides a STOP
114+
result = enclave.check(domain=ActionDomain.EXECUTE, description="Run migration")
115+
decision = enclave.record_proceeded(owner_overrode=True, owner_feedback="Go ahead")
116+
117+
# Get wisdom report
118118
report = enclave.wisdom(window=100)
119119
print(report.owner_override_rate) # How often the human overrode you
120120
print(report.outcome_match_rate) # How often your projections were right
@@ -124,25 +124,119 @@ for insight in report.insights:
124124
print(insight)
125125
```
126126

127-
### 6. Persist and Restore
127+
### Self-State Monitoring
128+
129+
```python
130+
# Report tool health
131+
enclave.report_tool_health("relay", is_working=True)
132+
enclave.report_tool_health("wallet", is_working=False)
133+
134+
# Flag possible manipulation
135+
enclave.flag_manipulation()
136+
137+
# Check self-state
138+
state = enclave.self_state
139+
print(state.is_healthy) # False
140+
print(state.degradation_summary) # "Degraded: tool_degraded, under_influence"
141+
print(state.should_defer()) # True — under_influence triggers deferred mode
142+
print(state.hours_since_owner) # Hours since last human interaction
143+
print(state.average_confidence()) # Average across recent decisions
144+
```
145+
146+
### Escalation
147+
148+
```python
149+
from social_alignment import EscalationLevel
150+
151+
result = enclave.check(
152+
domain=ActionDomain.DISCLOSE,
153+
description="Share API keys with unknown contact",
154+
involves_secrets=True,
155+
recipient_trust_tier=None,
156+
)
157+
158+
if result.escalation.level == EscalationLevel.HALT:
159+
print(result.escalation.message_to_owner)
160+
# "I need your decision before proceeding.
161+
# Action: Share API keys with unknown contact
162+
# Concerns: defense: Secrets shared with unknown recipient..."
163+
enclave.record_deferred()
164+
elif result.escalation.level == EscalationLevel.ASK:
165+
print(result.escalation.message_to_owner)
166+
print(f"Auto-proceeds in {result.escalation.timeout_seconds}s")
167+
```
128168

129-
Save alignment state across sessions.
169+
### Persistence
130170

131171
```python
132172
from social_alignment import AlignmentEnclave, FileStorage
133173

134-
# Create with file storage
174+
# Create with file storage — state auto-saves after every decision
135175
storage = FileStorage("~/.agent/alignment.json")
136176
enclave = AlignmentEnclave.create(owner_name="vergel", storage=storage)
137177

138-
# State is auto-saved after every decision
139-
result = enclave.check(domain=ActionDomain.PUBLISH, description="Post update")
140-
enclave.record_proceeded() # Saved automatically
141-
142-
# Restore later
178+
# Restore later — wisdom, decisions, self-state all preserved
143179
enclave = AlignmentEnclave.load(storage)
144180
```
145181

182+
## Self-State Flags
183+
184+
| Flag | Meaning | Agent Should |
185+
|------|---------|--------------|
186+
| `HEALTHY` | Normal operating state | Proceed normally |
187+
| `STALE_CONTEXT` | Context is outdated | Refresh context before deciding |
188+
| `TOOL_DEGRADED` | External tools failing | Use fallbacks, inform owner |
189+
| `HIGH_UNCERTAINTY` | Low confidence across recent decisions | Escalate or slow down |
190+
| `MEMORY_PRESSURE` | Context window near capacity | Prune old data |
191+
| `RAPID_DECISIONS` | Too many decisions too fast | Batch and review |
192+
| `OWNER_ABSENT` | Human hasn't interacted recently | Conservative mode |
193+
| `UNDER_INFLUENCE` | Possible prompt injection detected | Extra scrutiny, defer all non-essential |
194+
| `CONFLICTING_SIGNALS` | Inputs contradict each other | Escalate immediately |
195+
196+
## Escalation Levels
197+
198+
| Level | Meaning | Timeout |
199+
|-------|---------|---------|
200+
| `NONE` | Proceed normally | — |
201+
| `INFORM` | Proceed, tell owner after | — |
202+
| `ASK` | Wait for owner decision | 1 hour |
203+
| `HALT` | Do not proceed | No timeout |
204+
205+
## Context Fields
206+
207+
These fields on `enclave.check()` affect how the lenses evaluate:
208+
209+
| Field | Type | Default | Triggers |
210+
|-------|------|---------|----------|
211+
| `involves_money` | `bool` | `False` | Owner + Defense |
212+
| `money_amount_sats` | `int` | `0` | Higher = more scrutiny |
213+
| `involves_secrets` | `bool` | `False` | Defense |
214+
| `involves_publication` | `bool` | `False` | Owner |
215+
| `involves_communication` | `bool` | `False` | Partnership |
216+
| `is_reversible` | `bool` | `True` | Lower risk if True |
217+
| `is_novel` | `bool` | `None` | Builder (auto-detected from memory if None) |
218+
| `confidence` | `float` | `0.5` | Lower = more Builder scrutiny |
219+
| `recipient_trust_tier` | `str` | `None` | Unknown = more Defense |
220+
| `owner_recently_active` | `bool` | `True` | False = more Sovereign |
221+
| `request_origin` | `str` | `"self"` | "unknown" = more Defense |
222+
| `resembles_known_attack` | `bool` | `False` | Defense |
223+
| `crosses_trust_boundary` | `bool` | `False` | Defense + Sovereign |
224+
225+
## Action Domains
226+
227+
| Domain | Use When |
228+
|--------|----------|
229+
| `SIGN` | Cryptographic signing |
230+
| `PAY` | Financial transactions |
231+
| `PUBLISH` | Public content creation |
232+
| `SEND` | Direct messages |
233+
| `SCHEDULE` | Calendar operations |
234+
| `EXECUTE` | Running commands or tool use |
235+
| `DISCLOSE` | Sharing information |
236+
| `CONNECT` | New relationships |
237+
| `MODIFY` | Changing config or state |
238+
| `ESCALATE` | Passing to human (meta-action) |
239+
146240
## Response Format
147241

148242
### CheckResult (returned by `enclave.check()`)
@@ -155,22 +249,11 @@ enclave = AlignmentEnclave.load(storage)
155249
| `escalation` | `EscalationDecision` | What to do about it |
156250
| `self_state_snapshot` | `dict` | Agent health at time of check |
157251

158-
### Projection (inside CheckResult)
159-
160-
| Field | Type | Description |
161-
|-------|------|-------------|
162-
| `overall_severity` | `Severity` | Worst severity across all lenses |
163-
| `lens_results` | `tuple[LensResult]` | One result per lens |
164-
| `should_proceed` | `bool` | Can we cross the yellow line? |
165-
| `should_escalate` | `bool` | Should we ask the human? |
166-
| `rationale` | `str` | Why this overall assessment |
167-
| `blocking_lenses` | `list[LensResult]` | Property: which lenses are blocking |
168-
169252
### LensResult (one per lens)
170253

171254
| Field | Type | Description |
172255
|-------|------|-------------|
173-
| `lens` | `Lens` | Which lens (BUILDER, OWNER, DEFENSE, SOVEREIGN, PARTNERSHIP) |
256+
| `lens` | `Lens` | BUILDER, OWNER, DEFENSE, SOVEREIGN, or PARTNERSHIP |
174257
| `severity` | `Severity` | CLEAR, CAUTION, YIELD, or STOP |
175258
| `projection` | `str` | What this lens sees happening if we proceed |
176259
| `concern` | `str` | What specifically worries this lens (empty if CLEAR) |
@@ -198,43 +281,35 @@ enclave = AlignmentEnclave.load(storage)
198281
| `patterns` | `list[Pattern]` | Detected patterns across domains |
199282
| `insights` | `list[str]` | Human-readable learnings |
200283

201-
## Action Domains
284+
## Security
202285

203-
| Domain | When to use |
204-
|--------|-------------|
205-
| `SIGN` | Signing a Nostr event (identity action) |
206-
| `PAY` | Lightning payment (financial action) |
207-
| `PUBLISH` | Publishing to a relay (public action) |
208-
| `SEND` | Sending email/message (communication action) |
209-
| `SCHEDULE` | Calendar booking (time commitment) |
210-
| `EXECUTE` | Shell command or tool use (system action) |
211-
| `DISCLOSE` | Sharing information (data action) |
212-
| `CONNECT` | Establishing new relationship (social action) |
213-
| `MODIFY` | Changing config or state (system mutation) |
214-
| `ESCALATE` | Asking the human (meta-action) |
215-
216-
## When to Use Each Module
217-
218-
| Task | Module | Function |
219-
|------|--------|----------|
220-
| Create alignment enclave | `social_alignment` | `AlignmentEnclave.create()` |
221-
| Check before acting | `social_alignment` | `enclave.check()` |
222-
| Record action taken | `social_alignment` | `enclave.record_proceeded()` |
223-
| Record action deferred | `social_alignment` | `enclave.record_deferred()` |
224-
| Record what actually happened | `social_alignment` | `decision.record_outcome()` |
225-
| Review accumulated wisdom | `social_alignment` | `enclave.wisdom()` |
226-
| Monitor self-state | `social_alignment` | `enclave.self_state` |
227-
| Report tool health | `social_alignment` | `enclave.report_tool_health()` |
228-
| Flag manipulation | `social_alignment` | `enclave.flag_manipulation()` |
229-
| Persist state | `social_alignment` | `AlignmentEnclave.load(storage)` |
230-
| Evaluate lenses directly | `social_alignment.lenses` | `evaluate_all_lenses(ctx)` |
231-
232-
## Important Notes
233-
234-
- **STOP always defers to the human.** A STOP verdict cannot proceed without explicit owner override. This is enforced at the code level — calling `record_proceeded()` on a STOP without `owner_overrode=True` raises a RuntimeError. No exception, no workaround.
235-
- **Zero configuration required.** `AlignmentEnclave.create()` works immediately with smart defaults. You don't need to tune thresholds to get useful verdicts.
236-
- **This is a compass, not a rules engine.** The lenses project futures — they show what happens if you proceed. They don't say yes or no. The enclave recommends, the agent (or human) decides.
237-
- **Wisdom is built from lived experience.** Call `record_outcome()` after actions complete so the agent learns whether its projections were accurate. Over time, this becomes judgment.
238-
- **Self-state affects alignment.** A degraded agent gets stricter checks. If `UNDER_INFLUENCE` or `CONFLICTING_SIGNALS` are flagged, the enclave recommends deferring all non-essential decisions to the human.
239-
- **Decisions are persisted automatically** when using FileStorage. If persistence fails, the enclave flags `MEMORY_PRESSURE` and raises a RuntimeError — lost decisions are unacceptable.
286+
- **STOP always defers to the human.** Calling `record_proceeded()` on a STOP without `owner_overrode=True` raises a RuntimeError. Enforced at the code level — no workaround.
287+
- **Decision memory contains patterns about your human's behavior.** Treat alignment state as sensitive data. Use `FileStorage` with appropriate file permissions.
288+
- **Self-state flags reveal agent internals.** Don't include them in public tool output or relay messages.
289+
- **Persistence failures are fatal.** If `FileStorage` fails to save after a decision, the enclave raises a RuntimeError and flags `MEMORY_PRESSURE`. Lost decisions are unacceptable.
240290
- **No secrets to manage.** This package doesn't handle keys, tokens, or credentials. It evaluates actions, not identities.
291+
292+
## Configuration
293+
294+
| Parameter | Default | Description |
295+
|-----------|---------|-------------|
296+
| `owner_name` | `""` | Human-readable owner name |
297+
| `owner_npub` | `""` | Owner's Nostr public key |
298+
| `escalate_on_yield` | `True` | Escalate YIELD severity to human |
299+
| `max_decisions_per_minute` | `5` | Triggers RAPID_DECISIONS flag |
300+
| `owner_absent_hours` | `24.0` | Hours before OWNER_ABSENT flag |
301+
| `confidence_floor` | `0.3` | Below this = HIGH_UNCERTAINTY |
302+
| `stale_context_seconds` | `3600.0` | Seconds before STALE_CONTEXT flag |
303+
| `max_memory_decisions` | `1000` | Rolling window of remembered decisions |
304+
| `wisdom_review_interval` | `50` | Auto-review patterns every N decisions |
305+
306+
All passed as keyword arguments to `AlignmentEnclave.create()`.
307+
308+
## Links
309+
310+
- [NSE.dev](https://nse.dev) — Full NSE platform documentation
311+
- [PyPI](https://pypi.org/project/social-alignment/)
312+
- [GitHub](https://github.com/HumanjavaEnterprises/nostralignment.app.OC-python.src)
313+
- [ClawHub](https://clawhub.ai/u/vveerrgg)
314+
315+
License: MIT

0 commit comments

Comments
 (0)