Timmy-time-dashboard/docs/soul/VERSIONING.md

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:

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:

## 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:

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).