Get Started
In this section
Back to reference

15. Archive & Versioning

aDNA Specification v2.5 Section 15 of 20 Full text

Scan: Archive patterns for sync vs. git environments, retention policy, CLAUDE.md version tracking convention.

Decisions: C9, C10

15.1 Archive Pattern

The archive pattern varies by environment:

Sync environments (cloud storage, team sync tools):

  • Archive directories within content folders (e.g., how/backlog/archive/)
  • Session history uses how/sessions/history/YYYY-MM/
  • Archive-don’t-rename rule: move to archive/ instead of renaming files
  • Project-level archive/ within the nearest triad directory for vault-level archival

Git repositories:

  • Git history serves as the primary archive
  • archive/ subdirectories for visibly-deprecated items (documents users should see are retired)
  • Session history follows the same YYYY-MM/ pattern regardless of environment

15.2 Retention

Session history SHOULD NOT be auto-deleted. Manual cleanup after 6 months is acceptable if storage is a concern.

15.3 Versioning

aDNA instances track their own version via a comment in CLAUDE.md: <!-- vX.Y | YYYY-MM-DD -->.

Major version increments indicate structural changes. Minor version increments indicate significant content updates. Session history serves as the detailed changelog — no formal CHANGELOG.md is required.

15.4 Standard Versioning & Backwards Compatibility

The aDNA standard uses two versioning tracks:

  • Standard version (this document, adna_standard.md): Governs the normative specification — triad architecture, required files, conformance levels, naming conventions. Follows semantic versioning: vMajor.Minor.
  • Governance version (CLAUDE.md version field, CHANGELOG.md): Governs the operational implementation — protocols, templates, skills, tooling. Follows Major.Minor versioning.

Backwards compatibility promise:

  • Standard minor versions (e.g., v2.0 → v2.1) MUST NOT invalidate conformant instances. An instance conformant to aDNA v2.0 MUST remain conformant to aDNA v2.1.
  • Standard major versions (e.g., v2.x → v3.0) MAY introduce breaking changes. When they do, migration guidance MUST be provided.
  • Governance version changes are operational and do not affect standard conformance.

Version-cut checklist (v2.5, ADR-046 — the footer-lag anti-recurrence rule): on every version bump, the document’s four version-bearing surfaces MUST agree before the cut commits — (1) the frontmatter title, (2) the frontmatter updated date, (3) a new changelog comment line in the header block, and (4) the End of … footer line. A cut that leaves any of the four stale is incomplete. (This rule exists because the footer lagged the title across multiple historical bumps — most recently shipping “v2.3” inside the published v2.4 document.)