Changelog

Version history for the MASTERY.md framework.

v3.5.0 - April 1, 2026

Added

Architecture amendment flexibility - minor amendments (renamed fields, adjusted signatures) can now be logged in the changelog and applied autonomously. Structural changes still require human approval. Autonomy Boundaries table split into two rows.
Security checkpoint at Ship stage - new "Security review" row covering auth gaps, input validation, hardcoded secrets, PII exposure, injection risks
Compact fallback instruction - if `mastery-compact.md` doesn't exist, agents fall back to reading `mastery.md` directly instead of failing
Rollback & Recovery subsection - new section after Hotfix Rules covering when to revert vs hotfix, rollback procedure, and post-rollback steps
Reflect-to-Discuss feedback loop - Stage 6 now includes "Capture lessons for next feature" action. Discussion template gains "Lessons from Previous Features" section. Review template gains "Key Lessons to Carry Forward" section.

Changed

Cross-check trigger wording - "Every ~5 build tasks completed" changed to "Every ~5 build tasks, or after any high-complexity/high-risk task" for complexity-aware triggering
`mastery-compact.md` synced with all applicable changes (architecture flexibility, security checkpoint, compact fallback, cross-check wording, reflect loop)

v3.4.0 - March 21, 2026

Added

Research guidance (hybrid approach) - structured research support for projects and features where domain knowledge is insufficient
"Research & Prior Art" section added to both Project Discussion (Template #1) and Feature Discussion (Template #4) templates - always available, can be marked N/A when domain is well-understood
`research.md` document type - new conditional feature document (Template #17) for deep multi-topic research, created only when findings would overwhelm the discussion doc
Stage 1 (Discuss) action - new "Research if needed" row guiding teams to investigate knowledge gaps before proceeding
Ship stage release & README rules - Stage 5 (Ship) now includes mandatory steps for updating README/public docs and creating versioned releases
Document Ecosystem, Quick Reference, Naming Rules, and `mastery-compact.md` all updated for new document type

v3.3.0 - March 16, 2026

Added

Optional TC naming convention in testplan template — Go (`TestTC01_*`), Python (`test_tc01_*`), JS (`it("TC-01: ...")`) patterns for automated traceability between test cases and test code
Test Function field — optional column in TC table to link each test case to its implementation
Agent-asks-about-testing guidance in Build stage — agents ask developers about testing approach before writing tests
Testing awareness in AI Communication Style — agents ask about test auditing when `testplan.md` exists (both full and compact variants)

v3.2.0 - March 14, 2026

Added

`mastery-compact.md` — compact variant (~5k tokens vs ~25k) — AI-optimized version containing all rules, no templates. 80% token reduction for agents that don't need templates every session
Two-variant loading strategy in Context Loading Order — agents load compact by default, full file only when templates are needed
Document Ecosystem updates — both files listed in directory tree, Document Roles table, Required vs Optional table
AGENTS.md updates — project structure and loading order reference compact variant
README.md updates — two-variants table, updated Quick Start and Adopting instructions

Changed

Resuming Work section now references compact variant
AI Agent Quick Start updated for compact-first loading

v3.1.0 - March 13, 2026

Added

Strict context loading enforcement — AI agents must re-read `mastery.md` at the start of every new context/session
Project-level changelog document (`project-changelog.md`) — new required document type for tracking shipped features
Template #16 (Project Changelog Document)
Ship stage now includes "Update project changelog" action
Hotfix workflow updated to include project changelog
Project Initialization Step 4.5 for creating `project-changelog.md`

Changed

Resuming Work → For AI Agents now starts with `mastery.md` as step 1
AI Agent Quick Start reinforces "mandatory every session"
Autonomy boundaries expanded (AI can update project changelog)
Definition of Done expanded with project changelog checkbox

v3.0.1 - March 13, 2026

Added

Mid-project adoption guide - 8-step workflow for adopting Mastery into existing projects
Template #15 (Summary Document) for retroactive feature summaries
`_archive/` folder convention for preserving pre-Mastery docs
Mid-Project Adoption checklist in Quick Reference section

v3.0.0 - March 12, 2026

Changed

Restructured section order for progressive disclosure
Most critical information (Philosophy, AI Agent Protocol) moved to top
Operational content (Workflow, Templates) in middle
Reference material (Git, Definitions) at bottom
86 lines moved, 0 lines added or deleted

v2.0.0 - March 12, 2026

Initial Public Release

Complete 7-stage development lifecycle
AI Agent Protocol with autonomy boundaries
10+ document templates
Git branching strategy and commit conventions
Session handoff and continuity protocols

# Changelog
Version history for the MASTERY.md framework.
## v3.5.0 - April 1, 2026
### Added
- Architecture amendment flexibility - minor amendments (renamed fields, adjusted signatures) can now be logged in the changelog and applied autonomously. Structural changes still require human approval. Autonomy Boundaries table split into two rows.
- Security checkpoint at Ship stage - new "Security review" row covering auth gaps, input validation, hardcoded secrets, PII exposure, injection risks
- Compact fallback instruction - if `mastery-compact.md` doesn't exist, agents fall back to reading `mastery.md` directly instead of failing
- Rollback & Recovery subsection - new section after Hotfix Rules covering when to revert vs hotfix, rollback procedure, and post-rollback steps
- Reflect-to-Discuss feedback loop - Stage 6 now includes "Capture lessons for next feature" action. Discussion template gains "Lessons from Previous Features" section. Review template gains "Key Lessons to Carry Forward" section.
### Changed
- Cross-check trigger wording - "Every ~5 build tasks completed" changed to "Every ~5 build tasks, or after any high-complexity/high-risk task" for complexity-aware triggering
- `mastery-compact.md` synced with all applicable changes (architecture flexibility, security checkpoint, compact fallback, cross-check wording, reflect loop)
## v3.4.0 - March 21, 2026
### Added
- Research guidance (hybrid approach) - structured research support for projects and features where domain knowledge is insufficient
- "Research & Prior Art" section added to both Project Discussion (Template #1) and Feature Discussion (Template #4) templates - always available, can be marked N/A when domain is well-understood
- `research.md` document type - new conditional feature document (Template #17) for deep multi-topic research, created only when findings would overwhelm the discussion doc
- Stage 1 (Discuss) action - new "Research if needed" row guiding teams to investigate knowledge gaps before proceeding
- Ship stage release & README rules - Stage 5 (Ship) now includes mandatory steps for updating README/public docs and creating versioned releases
- Document Ecosystem, Quick Reference, Naming Rules, and `mastery-compact.md` all updated for new document type
## v3.3.0 - March 16, 2026
### Added
- Optional TC naming convention in testplan template — Go (`TestTC01_*`), Python (`test_tc01_*`), JS (`it("TC-01: ...")`) patterns for automated traceability between test cases and test code
- Test Function field — optional column in TC table to link each test case to its implementation
- Agent-asks-about-testing guidance in Build stage — agents ask developers about testing approach before writing tests
- Testing awareness in AI Communication Style — agents ask about test auditing when `testplan.md` exists (both full and compact variants)
## v3.2.0 - March 14, 2026
### Added
- `mastery-compact.md` — compact variant (~5k tokens vs ~25k) — AI-optimized version containing all rules, no templates. 80% token reduction for agents that don't need templates every session
- Two-variant loading strategy in Context Loading Order — agents load compact by default, full file only when templates are needed
- Document Ecosystem updates — both files listed in directory tree, Document Roles table, Required vs Optional table
- AGENTS.md updates — project structure and loading order reference compact variant
- README.md updates — two-variants table, updated Quick Start and Adopting instructions
### Changed
- Resuming Work section now references compact variant
- AI Agent Quick Start updated for compact-first loading
## v3.1.0 - March 13, 2026
### Added
- Strict context loading enforcement — AI agents must re-read `mastery.md` at the start of every new context/session
- Project-level changelog document (`project-changelog.md`) — new required document type for tracking shipped features
- Template #16 (Project Changelog Document)
- Ship stage now includes "Update project changelog" action
- Hotfix workflow updated to include project changelog
- Project Initialization Step 4.5 for creating `project-changelog.md`
### Changed
- Resuming Work → For AI Agents now starts with `mastery.md` as step 1
- AI Agent Quick Start reinforces "mandatory every session"
- Autonomy boundaries expanded (AI can update project changelog)
- Definition of Done expanded with project changelog checkbox
## v3.0.1 - March 13, 2026
### Added
- Mid-project adoption guide - 8-step workflow for adopting Mastery into existing projects
- Template #15 (Summary Document) for retroactive feature summaries
- `_archive/` folder convention for preserving pre-Mastery docs
- Mid-Project Adoption checklist in Quick Reference section
## v3.0.0 - March 12, 2026
### Changed
- Restructured section order for progressive disclosure
- Most critical information (Philosophy, AI Agent Protocol) moved to top
- Operational content (Workflow, Templates) in middle
- Reference material (Git, Definitions) at bottom
- 86 lines moved, 0 lines added or deleted
## v2.0.0 - March 12, 2026
### Initial Public Release
- Complete 7-stage development lifecycle
- AI Agent Protocol with autonomy boundaries
- 10+ document templates
- Git branching strategy and commit conventions
- Session handoff and continuity protocols