feat: add changelog schema for Keep a Changelog validation

Created comprehensive changelog-schema-v1.0.md to validate CHANGELOG.md files following the Keep a Changelog format. This schema demonstrates the practical application of the schema evolution system. **Schema Features**: - Section validation: Enforces [Unreleased] section presence - Version format validation: [X.Y.Z] - YYYY-MM-DD pattern - Semantic versioning compliance - ISO 8601 date format checking - Change type subsections: Added, Changed, Deprecated, Removed, Fixed, Security - Content pattern matching via x-markitect-content-control extensions - Structural validation via JSON Schema properties **Validation Results**: ✅ Successfully validates project CHANGELOG.md ✅ All section requirements met (7 sections checked, 11 found) ✅ All content requirements met ✅ All semantic checks passing **Implementation Notes**: - H1 "Changelog" title validated via JSON Schema structural checks - H2 sections validated via x-markitect-sections classifications - SectionValidator limitation: Only checks H2+ headings, not H1 - Workaround: Structural validation covers H1 title requirement **Philosophy**: "The release that validates itself" - v0.10.0 uses its own schema system to validate its CHANGELOG - Perfect showcase of schema evolution practical value - Demonstrates x-markitect extensions in real-world use case **Stage 2 Complete** per release-management-optimization workplan. Files: - markitect/schemas/changelog-schema-v1.0.md (new) - CHANGELOG.md (documented new schema)
2026-01-06 13:31:02 +01:00
parent 061ba88206
commit c4ee5cc645
2 changed files with 356 additions and 0 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -52,6 +52,14 @@ See history/YYMMDD-ROADMAOTOPIC/ directories for planning information of closed
  - Test coverage: 25 tests for semantic validators (16 section/content + 9 link), 100% passing
  - Full documentation: Semantic validation guide in SCHEMA_MANAGEMENT_GUIDE.md with examples
  - Complements existing structural AST validation for complete document compliance checking
+- **Changelog Schema**: Production schema for validating CHANGELOG.md files following Keep a Changelog format
+  - Schema file: `changelog-schema-v1.0.md` validates version history structure and formatting
+  - Enforces Unreleased section presence (required)
+  - Validates version format: `[X.Y.Z] - YYYY-MM-DD` with semantic versioning
+  - Validates change type subsections: Added, Changed, Deprecated, Removed, Fixed, Security
+  - Content pattern validation for version sections, date formats (ISO 8601), and change types
+  - Demonstrates real-world schema system usage: "The release that validates itself"
+  - Successfully validates project CHANGELOG.md with all semantic checks passing

 ### Changed
 - **Directory Reorganization**:
--- a/markitect/schemas/changelog-schema-v1.0.md
+++ b/markitect/schemas/changelog-schema-v1.0.md
@@ -0,0 +1,348 @@
+---
+schema: changelog-schema-v1.0
+version: "1.0"
+domain: changelog
+description: "JSON schema for Keep a Changelog format with version history validation"
+created: "2026-01-06"
+author: "MarkiTect Schema System"
+---
+
+# Changelog Schema v1.0
+
+## Overview
+
+This schema validates CHANGELOG.md files following the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. It enforces:
+
+- Unreleased section presence (required)
+- Version section format: `[X.Y.Z] - YYYY-MM-DD`
+- Standard change type subsections
+- Semantic versioning adherence
+- ISO 8601 date formatting
+
+## Purpose
+
+Ensures changelog files maintain consistent structure and formatting across releases, facilitating:
+- Automated release note generation
+- Version history tracking
+- Release validation workflows
+- Documentation consistency
+
+## Schema Definition
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Changelog Schema",
+  "description": "Validates Keep a Changelog format for project changelogs",
+
+  "x-markitect-metadata": {
+    "schema_name": "changelog-schema-v1.0",
+    "version": "1.0",
+    "domain": "changelog",
+    "created": "2026-01-06",
+    "author": "MarkiTect Schema System"
+  },
+
+  "x-markitect-sections": {
+    "[Unreleased]": {
+      "classification": "required",
+      "heading_level": 2,
+      "error_message": "Unreleased section is mandatory for tracking upcoming changes",
+      "content_instruction": "Use ## [Unreleased] heading. Section can be empty if no unreleased changes.",
+      "alternatives": ["UNRELEASED", "Unreleased"]
+    },
+    "Added": {
+      "classification": "optional",
+      "heading_level": 3,
+      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "content_instruction": "New features added in this release"
+    },
+    "Changed": {
+      "classification": "optional",
+      "heading_level": 3,
+      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "content_instruction": "Changes to existing functionality"
+    },
+    "Deprecated": {
+      "classification": "optional",
+      "heading_level": 3,
+      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "content_instruction": "Features that will be removed in future versions"
+    },
+    "Removed": {
+      "classification": "optional",
+      "heading_level": 3,
+      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "content_instruction": "Features removed in this release"
+    },
+    "Fixed": {
+      "classification": "optional",
+      "heading_level": 3,
+      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "content_instruction": "Bug fixes in this release"
+    },
+    "Security": {
+      "classification": "optional",
+      "heading_level": 3,
+      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "content_instruction": "Security fixes and vulnerabilities addressed"
+    }
+  },
+
+  "x-markitect-content-control": {
+    "title": {
+      "required_patterns": [
+        "^# Changelog$"
+      ],
+      "content_quality": {
+        "min_words": 1,
+        "max_words": 1
+      },
+      "error_message": "Title must be exactly '# Changelog'"
+    },
+    "introduction": {
+      "recommended_patterns": [
+        "Keep a Changelog",
+        "Semantic Versioning"
+      ],
+      "content_instruction": "Introduction should reference Keep a Changelog and Semantic Versioning standards"
+    },
+    "unreleased_section": {
+      "required_patterns": [
+        "## \\[Unreleased\\]"
+      ],
+      "content_quality": {
+        "min_words": 0
+      },
+      "error_message": "Unreleased section must use format: ## [Unreleased]"
+    },
+    "version_section": {
+      "required_patterns": [
+        "## \\[\\d+\\.\\d+\\.\\d+\\] - \\d{4}-\\d{2}-\\d{2}"
+      ],
+      "content_instruction": "Version sections must follow format: ## [X.Y.Z] - YYYY-MM-DD",
+      "error_message": "Version sections must use semantic versioning (X.Y.Z) with ISO 8601 dates (YYYY-MM-DD)"
+    },
+    "change_types": {
+      "recommended_patterns": [
+        "### Added",
+        "### Changed",
+        "### Deprecated",
+        "### Removed",
+        "### Fixed",
+        "### Security"
+      ],
+      "content_instruction": "Use standard Keep a Changelog change type subsections",
+      "error_message": "Change types should be one of: Added, Changed, Deprecated, Removed, Fixed, Security"
+    },
+    "link_references": {
+      "recommended_patterns": [
+        "\\[Keep a Changelog\\]\\(https://keepachangelog\\.com",
+        "\\[Semantic Versioning\\]\\(https://semver\\.org"
+      ],
+      "content_instruction": "Include reference links to Keep a Changelog and Semantic Versioning"
+    }
+  },
+
+  "x-markitect-validation-rules": {
+    "version_format": {
+      "pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
+      "description": "Version must follow semantic versioning: [MAJOR.MINOR.PATCH]"
+    },
+    "date_format": {
+      "pattern": "\\d{4}-\\d{2}-\\d{2}",
+      "description": "Date must be in ISO 8601 format: YYYY-MM-DD"
+    },
+    "version_ordering": {
+      "rule": "descending",
+      "description": "Versions should be listed in descending order (newest first)"
+    },
+    "unreleased_position": {
+      "rule": "first_section",
+      "description": "Unreleased section must come before all version sections"
+    }
+  },
+
+  "properties": {
+    "headings": {
+      "type": "object",
+      "description": "Document heading structure",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Title heading (should be 'Changelog')",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": "^Changelog$"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Version sections ([Unreleased] and [X.Y.Z] - YYYY-MM-DD)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": "^(\\[Unreleased\\]|\\[\\d+\\.\\d+\\.\\d+\\] - \\d{4}-\\d{2}-\\d{2})$"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 100
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Change type subsections (Added, Changed, etc.)",
+          "minItems": 0,
+          "maxItems": 500
+        }
+      },
+      "required": ["level_1", "level_2"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Introduction and change descriptions",
+      "minItems": 1,
+      "maxItems": 5000
+    },
+    "lists": {
+      "type": "array",
+      "description": "Change item lists",
+      "minItems": 0,
+      "maxItems": 1000
+    }
+  },
+  "required": ["headings", "paragraphs"]
+}
+```
+
+## Usage Examples
+
+### Valid Changelog Structure
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-01-06
+
+### Added
+- New feature A
+- New feature B
+
+### Fixed
+- Bug fix for issue #123
+```
+
+### Validation Command
+
+```bash
+# Ingest schema
+markitect schema-ingest markitect/schemas/changelog-schema-v1.0.md
+
+# Validate changelog
+markitect validate CHANGELOG.md --schema changelog-schema-v1.0.md --semantic
+```
+
+## Validation Checks
+
+### Required Elements
+- ✅ Title: Must be "# Changelog"
+- ✅ Unreleased section: `## [Unreleased]` must be present
+- ✅ Version format: `## [X.Y.Z] - YYYY-MM-DD` for all releases
+
+### Recommended Elements
+- ⭐ Introduction paragraph referencing Keep a Changelog
+- ⭐ Semantic Versioning reference
+- ⭐ At least one change type subsection per version
+
+### Content Patterns
+- Version sections use semantic versioning (MAJOR.MINOR.PATCH)
+- Dates in ISO 8601 format (YYYY-MM-DD)
+- Change types: Added, Changed, Deprecated, Removed, Fixed, Security
+- Bullet point lists for change items
+
+## Common Validation Errors
+
+### Missing Unreleased Section
+**Error**: "Unreleased section is mandatory for tracking upcoming changes"
+**Fix**: Add `## [Unreleased]` section at the top of version history
+
+### Invalid Version Format
+**Error**: "Version sections must use semantic versioning (X.Y.Z)"
+**Fix**: Use format `## [1.0.0] - 2026-01-06` not `## Version 1.0.0`
+
+### Invalid Date Format
+**Error**: "Date must be in ISO 8601 format: YYYY-MM-DD"
+**Fix**: Use `2026-01-06` not `Jan 6, 2026` or `01/06/2026`
+
+### Missing Change Type Subsections
+**Warning**: "Version should have at least one change type subsection"
+**Fix**: Add `### Added`, `### Fixed`, or other change type heading
+
+## Schema Extension Notes
+
+### Future Enhancements
+
+This schema could be extended with:
+
+1. **System Call Validation** (`x-markitect-validation-hooks`):
+   - Verify git tags match CHANGELOG versions
+   - Check version ordering consistency
+   - Validate date chronology
+
+2. **Agent Validation** (`x-markitect-validation-agents`):
+   - Semantic consistency checking
+   - Duplicate entry detection
+   - Version numbering logic validation
+
+3. **Cross-Reference Validation**:
+   - Link validation to issue trackers
+   - Commit hash verification
+   - Release note completeness checking
+
+## Keep a Changelog Standard
+
+This schema enforces the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) principles:
+
+- **Changelogs are for humans**, not machines
+- **One entry per version**
+- **Group changes by type** (Added, Changed, etc.)
+- **Versions and dates** for each release
+- **Latest version first**
+- **Unreleased section** for upcoming changes
+
+Combined with [Semantic Versioning](https://semver.org/), this enables consistent, readable version history.
+
+## Version History
+
+- **1.0** (2026-01-06): Initial schema release
+  - Basic structure validation
+  - Version and date format checking
+  - Change type subsection validation
+  - Keep a Changelog compliance
+
+## Related Schemas
+
+- `schema-schema-v1.0.md` - Metaschema for validating schemas
+- `manpage-schema-v1.0.md` - Schema for manual pages
+- `api-documentation-schema-v1.0.md` - Schema for API documentation
+
+## License
+
+Part of MarkiTect Schema System