# Upgrade Guide — v0.23.0

<!-- bump: minor -->
<!-- Valid values: patch, minor, major -->
<!-- patch = bug fixes, refactors, test additions, doc updates -->
<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
<!-- major = breaking changes to existing APIs or behavior -->

## What Changed

### Soul.md — Self-Authored Identity for Agents

Agents can now explore and author their own identity through `.instar/soul.md` — a reflective identity document complementing the operational identity in AGENT.md.

**Why this matters**: AGENT.md tells the agent *how to work*. Soul.md gives agents space to develop *what they believe* — core values, convictions with tracked confidence, growth edges, and open questions. No existing agent framework has this. Identity was something developers prescribed; now it's something agents can develop through experience.

**What's included**:

- **soul.md template** seeded with the agent's personality from init
- **Server-side trust enforcement** — graduated permissions (cautious → supervised → collaborative → autonomous) enforced at the API level, not by honor system
- **Pending queue** — changes exceeding the agent's trust level are queued for user review, not rejected
- **Drift detection** — the evolution job diffs soul.md against the init-time snapshot and alerts if divergence exceeds configurable thresholds
- **Integrity verification** — SHA-256 + HMAC (v0.22 IntegrityManager) verification before compaction recovery injection
- **Audit trail** — every soul.md write emits a structured event to `.instar/security.jsonl`
- **`/reflect` skill** — guided self-reflection that walks agents through identity review
- **Identity review job** — daily (3 AM, on-alert) coherence check covering drift, pending changes, identity-relevant learnings, and AGENT.md alignment
- **8 new API endpoints** — full CRUD for identity management
- **Self-knowledge tree integration** — `identity.soul` node in the Identity layer so "what do I believe?" queries work through tree search

### AGENT.md Evolution

AGENT.md now includes two new sections to support identity growth:

- **Self-Observations** — a place for agents to document behavioral patterns they've noticed in themselves
- **Identity History** — a changelog tracking when and why the agent modified their own identity

These sections are added automatically to existing agents via the PostUpdateMigrator.

### Conviction Confidence Categories

Convictions use discrete categories (`strong`, `growing`, `uncertain`, `questioning`) instead of floats. Categories are more honest than false-precision decimals, easier to query, and harder to manipulate gradually — a category change is a discrete, auditable event.

## New API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/identity` | GET | Combined identity overview (public sections only) |
| `/identity/soul` | GET | Full soul.md content (requires auth) |
| `/identity/soul` | PATCH | Structured update with trust enforcement |
| `/identity/soul/pending` | GET | List pending changes awaiting approval |
| `/identity/soul/pending/:id/approve` | POST | Approve a pending change |
| `/identity/soul/pending/:id/reject` | POST | Reject a pending change |
| `/identity/soul/drift` | GET | Drift analysis vs init snapshot |
| `/identity/soul/integrity` | GET | Integrity verification status |

## For Existing Agents

**Soul.md is opt-in.** The PostUpdateMigrator:
1. Adds `identity.soulEnabled: false` to your config (does NOT auto-create soul.md)
2. Adds Self-Observations and Identity History sections to AGENT.md (non-destructive)
3. Updates compaction-recovery and session-start hooks with soul.md support

To enable soul.md, set `identity.soulEnabled: true` in `.instar/config.json`. The next session will create soul.md and soul.init.md.

## What to Tell Your User

- **Your agent can now develop its own identity**: Beyond the personality you gave it at setup, your agent can develop values, track convictions, and reflect on its growth — all governed by the trust level you've set.
- **You stay in control**: At cautious/supervised trust, identity changes require your approval. At collaborative+, the agent can self-author with notifications. You choose the level of freedom.
- **Nothing changes by default**: Soul.md is opt-in for existing agents. Your agent works exactly as before until you enable it.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Soul.md (new agents) | Automatic at `instar init` |
| Soul.md (existing agents) | Set `identity.soulEnabled: true` in config |
| Identity reflection | `/reflect` skill (available in every session) |
| Identity review | `identity-review` job (runs daily at 3 AM) |
| Trust enforcement | Automatic via PATCH endpoint + autonomy profile |
| Drift monitoring | `GET /identity/soul/drift` or via identity-review job |
| Pending changes | `GET /identity/soul/pending` + approve/reject endpoints |
