Provides high-level overview of MarkiTect from value and functional perspective:
- What MarkiTect is and why it matters
- Core capabilities (Information Spaces, Schema Management, etc.)
- Practical use cases across different domains
- Key benefits for different user types
- Getting started guidance
- Philosophy and design principles
Focuses on user value and functionality without implementation details.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implements optional git-based version control for information spaces:
- HistoryConfig model for configuring history tracking
- Commit, Branch, HistoryEntry, DiffResult models
- IHistoryBackend and IHistoryQuery interfaces
- GitHistoryBackend using git CLI for version control
- GitHistoryEventHandler for event-driven auto-commits
- HistoryEventCoordinator for managing space history
- HistoryQueryService for high-level history queries
- Automatic commits on DOCUMENT_ADDED/REMOVED/CONTENT_CHANGED events
- Support for:
* Commit log with pagination and filtering
* Diff between versions
* File content at specific versions
* Branch creation and switching
* Version restoration
* Uncommitted changes detection
- 43 comprehensive unit tests with git availability checks
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements space composition and inheritance features:
- SpaceReference model for space-to-space references (includes, extends, links_to, composed_of)
- Variable inheritance through parent chain with local override
- Config inheritance with source tracking
- Access control models (SpacePermission, SpaceRole, AccessLevel)
- InheritanceResolver for walking parent chains
- AccessControlService for permission management
- ComposableSpaceService integrating all composability features
- Circular reference detection for EXTENDS references
- SQLite repositories for references and permissions
- 57 comprehensive unit tests
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements API layer for Information Spaces:
- GraphQL schema types for spaces, documents, variables
- GraphQL queries and mutations for space operations
- CLI command group with all space management commands
- Resolver functions connecting GraphQL to SpaceService
- 38 unit tests for API components
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements HTML rendering system for Information Spaces:
- SpaceRenderer: Abstract base class for renderers
- RenderConfig: Configuration for format, theme, TOC, etc.
- RenderResult: Immutable result with content hash and metadata
- ThemeConfig: Layered theme system with customization
- CompositeRenderer: Multi-format renderer delegation
- MarkdownToHTMLRenderer: Full markdown-to-HTML conversion
- Theme support (github, dark, minimal, academic)
- Code block handling
- Link target="_blank" for external links
- Table of contents generation
- Heading ID generation for navigation
- HTMLRendererFactory: Factory for common renderer configurations
- SpaceRenderingService: Orchestration layer
- Transclusion variable substitution
- Render caching with automatic invalidation
- Event emission (RENDER_STARTED, RENDER_COMPLETED, RENDER_FAILED)
- Batch rendering support
- Statistics tracking
- SpaceRenderingServiceBuilder: Fluent builder pattern
60 unit tests covering all components.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move topic from roadmap/ to history/
- Add DONE.md with comprehensive completion summary
- Topic fully complete with all 9 optimizations implemented
- Exceeded original scope (Stages 1-2 + all of Stage 3)
- Ready for archive
Add release notes extraction from CHANGELOG for publishing:
- Create ChangelogParser class to extract version sections from CHANGELOG
- Support multiple output formats: markdown, plain text, HTML
- Add 'release notes VERSION' CLI command to extract notes
- Auto-detect latest version if not specified
- Support piping to gh/gitea release commands
- Save to file with --output option
- Plain text format removes markdown formatting
- HTML format converts markdown to HTML
This streamlines creating release notes for GitHub/Gitea releases
by extracting CHANGELOG content automatically.
Usage:
release notes 0.10.0 # Extract markdown notes
release notes # Latest version
release notes 0.10.0 --format plain # Plain text
release notes 0.10.0 -o notes.md # Save to file
release notes 0.10.0 | gh release create v0.10.0 -F -
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add automated schema ingestion from markitect/schemas/ directory:
- Create auto_ingest_schemas() function in schema_loader module
- Automatically detect and ingest .md schema files from schemas/
- Skip schemas that are already ingested in database
- Return detailed results with ingested/skipped/failed lists
- Add 'markitect schema-auto-ingest' CLI command
- Support verbose mode for detailed progress reporting
- Useful for post-install setup and development workflows
This eliminates the manual step of running schema-ingest for each
bundled schema file, streamlining schema management.
Usage:
markitect schema-auto-ingest # Ingest all new schemas
markitect schema-auto-ingest --verbose # Show detailed progress
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add automated CHANGELOG section preparation for releases:
- Create ChangelogEditor class for programmatic CHANGELOG.md editing
- Implement create_version_section() to create new release sections
- Automatically move [Unreleased] content to new version section
- Add 'release prepare VERSION' CLI command to prepare CHANGELOG
- Validate CHANGELOG after edit to ensure correctness
- Support custom release dates with --date option
- Provide helpful feedback about content movement
This streamlines release preparation by automating the manual task of
creating version sections and moving unreleased changes.
Usage:
release prepare 0.11.0 # Uses today's date
release prepare 0.11.0 --date 2026-01-15
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add version-tag consistency validation to prevent mismatched releases:
- Integrate validate_changelog_version() into create_tag() workflow
to ensure CHANGELOG has version section before creating git tag
- Add check_version_consistency() method to ReleaseManager for
manual consistency verification
- Add 'release check-consistency --version X.Y.Z' CLI command to
verify CHANGELOG and git tag alignment
- Prevent tag creation if CHANGELOG missing version section
- Provide helpful tips when validation fails
This ensures git tags and CHANGELOG versions stay synchronized,
preventing incomplete or inconsistent releases.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add comprehensive CHANGELOG validation to release validation process:
- Add _validate_changelog() method that validates CHANGELOG.md against
changelog-schema-v1.0.md using markitect validate --semantic
- Add validate_changelog_version() to check version section exists with
proper date format and Unreleased section
- Add check_version_tag_consistency() to verify CHANGELOG versions
match git tags
- Integrate CHANGELOG validation into validate_release_state()
- Add CHANGELOG-specific recommendations to _get_recommendations()
This prevents releases with invalid or inconsistent CHANGELOG files,
catching format errors before they become problems.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Added --push/--no-push flag to release tag command for explicit control
over tag pushing behavior.
**Implementation**:
- Added --push/--no-push flag to CLI tag command (default: --push)
- Updated ReleaseManager.create_tag to accept push parameter
- Updated GitManager.create_tag to conditionally push based on flag
- Maintains backward compatibility (defaults to pushing)
**Usage**:
```bash
# Default behavior - creates and pushes tag
release tag --version 0.11.0
# Explicit push (same as default)
release tag --version 0.11.0 --push
# Create tag but don't push (manual push later)
release tag --version 0.11.0 --no-push
```
**Output when --no-push used**:
```
✅ Tag v0.11.0 created
💡 Push tag with: git push origin v0.11.0
```
**Benefits**:
- Makes push behavior explicit and controllable
- Prevents accidental pushes in some workflows
- Defaults to safe behavior (automatic push)
- Helpful reminder shown when --no-push used
**Files Modified**:
- capabilities/release-management/src/release_management/cli/main.py
- capabilities/release-management/src/release_management/core/manager.py
- capabilities/release-management/src/release_management/git/manager.py
Optimizations completed: 2/9 (High Priority)
Added unpushed tag detection to release status command to prevent
forgotten tag pushes (the critical issue from v0.10.0 release).
**Implementation**:
- Added `get_unpushed_tags()` method to GitManager
- Compares local tags with remote tags (git ls-remote)
- Handles annotated tags correctly (strips ^{} suffix)
- Added unpushed_tags to repository status dict
**CLI Enhancement**:
- `release status` now shows unpushed tags with warning emoji
- Lists all unpushed tags
- Provides helpful command to push them
**Output Example**:
```
⚠️ Unpushed Tags: 2 tag(s) not pushed to origin
- v0.9.0
- v0.10.0
💡 Push tags with: git push origin v0.9.0 v0.10.0
Or push all tags: git push --tags
```
**Testing**: Verified with current repo (no unpushed tags after push)
**Files Modified**:
- capabilities/release-management/src/release_management/git/manager.py
- capabilities/release-management/src/release_management/cli/main.py
**Documentation**: Added comprehensive IMPLEMENTATION_PLAN.md with
all 9 optimizations detailed (13.5 hours total estimated)
This solves the #1 critical issue from OPTIMIZATION_ASSESSMENT.md.
Added critical optimization #1 based on v0.10.0 release experience:
**Issue**: git status doesn't show unpushed tags, leading to forgotten tag pushes
**Impact**: v0.9.0 and v0.10.0 tags weren't pushed, plus older version tags
**Solution**: Enhanced release status or git hook to show unpushed tags
Total optimizations identified: 9 (was 8)
- High Priority: 4 (added unpushed tags visibility)
- Medium Priority: 3
- Low Priority: 2
Ready to implement all optimizations systematically.
Added comprehensive documentation to release-management-optimization topic:
**RELEASE_SUMMARY.md**:
- Complete v0.10.0 release documentation
- Build artifacts, testing results, validation status
- Git statistics and file changes
- Next steps and manual actions required
**OPTIMIZATION_ASSESSMENT.md**:
- Post-release analysis of what worked vs. issues
- Identified 8 optimization opportunities across 3 priority levels
- Detailed Stage 3 implementation recommendations
- Three options for next steps (Complete Stage 3, Quick Wins, or Move On)
**Key Finding**: Forgot to push tags (git push doesn't include tags by default)
**Action Required**: `git push --tags` to push v0.9.0 and v0.10.0 tags
**Recommendation**: Implement Stage 3 (2 hours) for automated validation
and tag pushing to prevent similar issues in future releases.
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)
**Critical Fixes for v0.10.0 Release**:
1. **Fixed setuptools-scm Configuration** (pyproject.toml):
- Added git_describe_command with --match 'v*' pattern
- Prevents setuptools-scm from parsing non-version tags
- Resolves "markitect --version" returning "unknown"
- Version detection now works correctly (0.9.1.dev76)
2. **Retroactively Created v0.9.0 Git Tag**:
- Tagged commit b9c1b90 from 2025-11-14
- Maintains version history integrity
- CHANGELOG documented v0.9.0 but tag was missing
- Enables proper version progression to v0.10.0
3. **Prepared CHANGELOG.md for v0.10.0 Release**:
- Created [0.10.0] - 2026-01-06 section
- Moved all Unreleased content to v0.10.0
- Documented version detection fixes
- Documented v0.9.0 retroactive tag creation
**Issue Identified**: Non-version git tags (e.g.,
"testdrive-jsui-migration-phase4-complete") were causing
setuptools-scm to crash with AssertionError.
**Solution**: Configure git describe to only match version tags
using --match 'v*' pattern, filtering out non-version tags.
**Result**: Version command now works correctly, showing
development version based on v0.9.0 + 76 commits.
**Next Step**: Ready to proceed with Stage 2 (CHANGELOG schema)
per release-management-optimization workplan.
Created comprehensive staged workplan for enhancing release management
infrastructure with robust validation using the schema system.
**Critical Issues Identified**:
- setuptools-scm missing tag_regex configuration
- markitect --version returns 'unknown' instead of actual version
- CHANGELOG shows v0.9.0 (2025-11-14) but git tag never created
- No validation for CHANGELOG format or version-tag consistency
**Solution Approach**:
Create changelog-schema-v1.0.md to validate Keep a Changelog format,
demonstrating schema evolution in real-world use case.
**Staged Workplan**:
- Stage 1 (45 min): Critical fixes to unblock v0.10.0 release
- Stage 2 (2.5 hrs): CHANGELOG schema creation and validation
- Stage 3 (2 hrs): Release capability enhancements
- Stage 4 (optional): Schema system extensions
**Showcase Feature**: 'The release that validates itself'
- v0.10.0 uses its own schema system to validate its CHANGELOG
- Perfect demonstration of schema evolution practical value
**Next Version**: v0.10.0 (not v0.9.0)
- CHANGELOG already shows v0.9.0 as released
- Must maintain version history integrity
This commit closes the schema-evolution topic (260105) by adding the final
deliverable (ADR schema) and fixing markdown schema support across commands.
**ADR Schema Created**:
- Comprehensive Architecture Decision Record validation schema
- 12 section classifications (7 required, 2 recommended, 2 optional, 3 improper/discouraged)
- Content pattern validation for ADR formatting rules (status dates, decision statements, rationale structure)
- Quality metrics for completeness (word counts, sentence counts)
- Follows title case naming convention (Status, Context, Decision, etc.)
**Markdown Schema Support Fixed**:
- Fixed `markitect validate` command to support .md schemas
- Added load_schema_from_path() for both .json and .md files
- Updated structural and semantic validation to use schema dict
- Fixed `markitect generate-stub` command to support .md schemas
- Uses load_schema_from_path() instead of direct JSON loading
- Created DocumentWrapper class in semantic_validator.py
- Extracts headings from AST tokens (heading_open, inline)
- Provides get_headings_by_level() interface expected by validators
- Enables section validation to work with real documents
**Topic Closure**:
- Updated SCHEMA_EVOLUTION_WORKPLAN.md with completion summary
- Phases 1-3: 100% complete (via Schema-of-Schemas and Semantic Validation)
- Phase 4: Deferred as future enhancement (15-20 sessions)
- Phase 5: 70% complete (docs done, CI/CD templates deferred)
- Created DONE.md with comprehensive task checklist
- Generated ADR template stub (examples/templates/adr-template.md)
- Moved topic from roadmap/ to history/260105-schema-evolution/
**Files Changed**:
- markitect/cli.py: Added markdown schema support to validate and generate-stub
- markitect/semantic_validator.py: Added DocumentWrapper class for AST parsing
- markitect/schemas/adr-schema-v1.0.md: New ADR validation schema (560 lines)
- examples/templates/adr-template.md: Generated ADR template stub
- history/260105-schema-evolution/: Moved completed topic to history
**Status**: Schema evolution topic successfully closed with ADR schema as final deliverable.
All schema commands now support markdown schemas. Section validation working correctly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Naming Convention Updates:
- Renamed history/2026-01-06-semantic-document-validation → history/260106-semantic-document-validation
- Documented yymmdd- format convention in history/README.md and roadmap/README.md
- Updated all date references in WORKPLAN.md and DONE.md
- Fixed SCHEMA_MANAGEMENT_GUIDE.md references to use yymmdd- format
Convention Details:
- Format: yymmdd-topic-name (e.g., 260106-semantic-document-validation)
- Benefits: Concise while maintaining chronological sorting
- Examples documented in both README files
- Applies to both roadmap/ and history/ directories
This establishes a consistent timestamp prefix convention that Claude and its agents should follow.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Repository Cleanup:
- Moved roadmap/20260106-semantic-document-validation → history/2026-01-06-semantic-document-validation
- Added completion summary to WORKPLAN.md documenting all 6 phases
- Created DONE.md with detailed list of accomplished tasks
- Documented all deliverables, commits, and success metrics
Topic Status: COMPLETED on 2026-01-06
- All phases complete: Section, Content, Link validation
- 25 tests passing (100% coverage)
- Full documentation and CLI integration
- Production ready
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Added link validation details to semantic validation entry:
- Internal link validation (fragments and file paths) by default
- External link validation with --check-links flag (opt-in)
- Email validation for mailto: links
- Updated test coverage: 25 tests (16 section/content + 9 link)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implement comprehensive link validation as part of semantic validation:
Core Features:
- Link classification: internal, external, fragment, email
- Internal link validation: fragment anchors and file paths
- External link validation: HTTP/HTTPS with configurable timeout
- Email validation: mailto: link format checking
- Fragment policy enforcement: allow/disallow fragment identifiers
Link Validator:
- markitect/validators/link_validator.py - Full link validation implementation
- Supports x-markitect-content-control.link_validation configuration
- Default: check internal links, skip external (fast)
- Opt-in external checking with --check-links flag
Integration:
- Updated SemanticValidator to include link_result in reports
- CLI already supports --check-links flag (line 1629 in cli.py)
- Link validation runs by default for internal links (fast)
- External link checking requires explicit --check-links flag
Test Coverage:
- Added 9 comprehensive tests for LinkValidator
- Tests cover: classification, broken links, fragments, email, statistics
- All 25 semantic validator tests passing (100%)
Documentation:
- Updated SCHEMA_MANAGEMENT_GUIDE.md with link validation section
- Added examples for broken links and external link checking
- Documented link types, validation rules, and configuration
Statistics Tracking:
- Links checked, internal/external/fragment/email counts
- Detailed error/warning reporting with line numbers
- Integration with existing semantic validation reporting
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Updated submodule reference after rebasing local commits on top of
remote changes. Local commits for project agent and TODO.md integration
now applied after remote updates to keepaTodofile and keepaContributingfile
agents.
Rebased commits:
- afc038d: agent: updated kaizen project agent
- 4b02ec5: feat: update project-management agent for TODO.md integration
Remote commits integrated:
- d372aea: Update agents/agent-keepaContributingfile.md
- 850a09e: Update agents/agent-keepaTodofile.md
Moved schema-of-schemas planning artifacts from roadmap to history
with datestamp prefix, marking completion of all 6 implementation phases.
**Changes:**
- Moved roadmap/schema-of-schemas/ → history/2026-01-05-schema-of-schemas/
- Updated all documentation references to new location
- Marked implementation as completed in TODO.md
- Updated CHANGELOG.md to reflect archived status
**Implementation Summary:**
All 6 phases completed successfully:
- Phase 1: Filename validation (50 tests)
- Phase 2: Markdown schema loader (35 tests)
- Phase 3: Schema-for-schemas metaschema (12 tests)
- Phase 4: Schema migration (2 migrated, 3 deleted)
- Phase 5: CLI enhancements (multi-schema validation)
- Phase 6: Integration testing and documentation
**Deliverables:**
- 97 unit tests (100% passing)
- 4 production schemas in registry
- Comprehensive user documentation
- Updated examples (manpages, terminology)
- Complete schema management system
The schema-of-schemas topic is now complete and archived for
historical reference.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Updated example documentation to use the new schema-of-schemas standard
with markdown schema format and multi-schema validation commands.
**Manpage Example Updates:**
- Changed schema reference from markdown-manpage-schema.json to manpage-schema-v1.0.md
- Updated all commands to use new multi-schema validation syntax
- Added examples of number-based validation (markitect schema-validate 2)
- Added examples of batch validation (--all, ranges, lists)
- Updated integration examples (CI/CD, pre-commit hooks, Makefile)
- Documented schema registry workflow
**Terminology Example Updates:**
- Changed schema reference from terminology-schema.json to terminology-schema-v1.0.md
- Updated all validation commands to use new CLI syntax
- Added examples of schema-list and numbered selection
- Added batch validation examples
- Updated GitHub Actions and pre-commit hook examples
- Documented schema registry access methods
**Key Changes:**
- All schema filenames now follow {domain}-schema-v{major}.{minor}.md convention
- Commands use schema registry with numbered or filename selection
- Batch validation examples added throughout
- Integration examples updated to new standard
- Documentation reflects markdown-first schema format
All schemas validated successfully against metaschema.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Enhanced schema-list and schema-validate commands to support efficient
batch validation of multiple schemas, especially useful when the
metaschema changes.
**schema-list enhancements:**
- Added numbered references (#1, #2, etc.) to all output formats
- Simple format: [1] prefix for each schema
- Table format: # column as first column
- JSON/YAML: number field added to each schema
**schema-validate enhancements:**
- Number selection: `markitect schema-validate 1`
- Range selection: `markitect schema-validate 1-3`
- List selection: `markitect schema-validate 1,3,5`
- Batch validation: `markitect schema-validate --all`
- Filename selection: `markitect schema-validate schema.md`
- Filesystem path: `markitect schema-validate ./schema.md`
- Batch results displayed as clear summary table
- Registry schemas take precedence with filesystem fallback
- Full backward compatibility maintained
**Implementation details:**
- Added ValidationResult dataclass for structured results
- Added helper functions: parse_schema_selector, resolve_schema_source,
is_filesystem_path, format_validation_summary
- Changed schema_selector from Path to str for flexible input
- Added --all flag for validating all registered schemas
- Comprehensive error handling and helpful usage messages
**Testing:**
- All selection methods tested and working
- Backward compatibility verified
- Parsing utilities tested with unit tests
Completes Phase 5 of Schema-of-Schemas implementation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
