# SOUL.md Versioning System

How SOUL.md versions work, how to bump them, and how to trace identity evolution.

---

## Version Format

SOUL.md versions follow semantic versioning: `MAJOR.MINOR.PATCH`

| Digit | Increment when... | Examples |
|-------|------------------|---------|
| **MAJOR** | Fundamental identity change | New prime directive; a core value removed; agent renamed or merged |
| **MINOR** | Capability or identity growth | New value added; new constraint added; new role extension section |
| **PATCH** | Clarification only | Wording improved; typo fixed; example updated; formatting changed |

Initial release is always `1.0.0`. There is no `0.x.x` — every deployed soul
is a first-class identity.

---

## Lineage and the `extends` Field

Sub-agents carry a lineage reference:

```yaml
extends: "timmy-base@1.0.0"
```

This means: "This soul was authored against `timmy-base` version `1.0.0`."

When the base soul bumps a MAJOR version, all extending souls must be reviewed
and updated. They do not auto-inherit — each soul is authored deliberately.

When the base soul bumps MINOR or PATCH, extending souls may but are not
required to update their `extends` reference. The soul author decides.

---

## Changelog Format

Every SOUL.md must contain a changelog table at the bottom:

```markdown
## Changelog

| Version | Date | Author | Summary |
|---------|------|--------|---------|
| 1.0.0 | 2026-03-23 | claude | Initial soul established |
| 1.1.0 | 2026-04-01 | timmy  | Added Audience Awareness section |
| 1.1.1 | 2026-04-02 | gemini | Clarified constraint #2 wording |
| 2.0.0 | 2026-05-10 | claude | New prime directive post-Phase 8 |
```

Rules:
- Append only — never modify past entries.
- `Author` is the agent or human who authored the change.
- `Summary` is one sentence describing what changed, not why.
  The commit message and linked issue carry the "why".

---

## Branching and Forks

If two agents are derived from the same base but evolve separately, each
carries its own version number. There is no shared version counter.

Example:
```
timmy-base@1.0.0
    ├── seer@1.0.0  (extends timmy-base@1.0.0)
    └── forge@1.0.0 (extends timmy-base@1.0.0)

timmy-base@2.0.0  (breaking change in base)
    ├── seer@2.0.0  (reviewed and updated for base@2.0.0)
    └── forge@1.1.0 (minor update; still extends timmy-base@1.0.0 for now)
```

Forge is not "behind" — it just hasn't needed to review the base change yet.
The `extends` field makes the gap visible.

---

## Storage

Soul files live in two locations:

| Location | Purpose |
|----------|---------|
| `memory/self/soul.md` | Timmy's base soul — the living document |
| `docs/soul/extensions/<name>.md` | Sub-agent extensions — authored documents |
| `docs/soul/SOUL_TEMPLATE.md` | Blank template for new agents |

The `memory/self/soul.md` is the primary runtime soul. When Timmy loads his
identity, this is the file he reads. The `docs/soul/extensions/` files are
referenced by the swarm agents at instantiation.

---

## Identity Snapshots

For every MAJOR version bump, create a snapshot:

```
docs/soul/history/timmy-base@<old-version>.md
```

This preserves the full text of the soul before the breaking change.
Snapshots are append-only — never modified after creation.

The snapshot directory is a record of who Timmy has been. It is part of the
identity lineage and should be treated with the same respect as the current soul.

---

## When to Bump vs. When to File an Issue

| Situation | Action |
|-----------|--------|
| Agent behavior changed by new code | Update SOUL.md to match, bump MINOR or PATCH |
| Agent behavior diverged from SOUL.md | File `[soul-gap]` issue, fix behavior first, then verify SOUL.md |
| New phase introduces new capability | Add Role Extension section, bump MINOR |
| Prime directive needs revision | Discuss in issue first. MAJOR bump required. |
| Wording unclear | Patch in place — no issue needed |

Do not bump versions without changing content. Do not change content without
bumping the version.

---

## Validation and CI

Run the soul validator before committing any SOUL.md change:

```bash
python scripts/validate_soul.py <path/to/soul.md>
```

The validator checks:
- Frontmatter fields present and populated
- Version follows `MAJOR.MINOR.PATCH` format
- All required sections present
- Changelog present with at least one entry
- No high-confidence contradictions detected

Future: add soul validation to the pre-commit hook (`tox -e lint`).