voidea/docs/blocks/VERSIONS.md

Versioning Rules - VoIdea

Date: 2026-05-10

---

Format

MAJOR.MINOR.PATCH (SemVer)

• MAJOR (X.0.0): breaking changes, full releases
• MINOR (0.X.0): new functionality, backward compatible
• PATCH (0.0.X): bug fixes

---

CHANGELOG

Location: CHANGELOG/

• New file on X change: vX.0.md
• New file on Y change: vX.Y.md
• PATCH appended to existing file

Examples:

• CHANGELOG/v1.0.md (1.0.0 -> 1.0.5)
• CHANGELOG/v1.1.md (1.1.0 -> 1.1.3)
• CHANGELOG/v2.0.md (2.0.0 -> ...)

---

Generation

Auto-generated by SpecAgent on version change.

---

Agent Versioning

Each system agent is versioned independently (A.B.C).

Rules

Component	When	Who
A (major)	Breaking change in public interface	EvolutionAgent
B (minor)	New capability (method, role, prompt)	EvolutionAgent
C (patch)	Internal fixes, no behavior change	Agent itself (auto)

Mechanism

1. Agent runs → compute_checksum() (SHA256 of __file__)
2. Compares with AgentConfig.checksum in DB
3. Mismatch → auto-bump patch → update changelog → save new checksum
4. EvolutionAgent handles minor/major bumps via capability analysis

Storage

CHANGELOG/agents/<agent_name>.md — flat file, all history in one file.

Format:

# audit_agent Changelog

## 1.0.2 (2026-05-10)
- Fixed: ruff output parsing for Windows paths

---

Updated: 2026-05-10