tegwick
f3aaec99bb
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Completed Phase 3 of the schema-of-schemas implementation with a comprehensive metaschema that validates all MarkiTect schema files against conventions and standards. Metaschema Implementation (schema-schema-v1.0.md - 650+ lines): - Validates core JSON Schema fields ($schema, $id, title, description) - Validates MarkiTect version field (SemVer: major.minor.patch) - Validates $id URL format (HTTPS with version path) - Validates MarkiTect extensions: - x-markitect-sections: section classifications and content rules - x-markitect-content-control: pattern and quality validation - x-markitect-metadata: status, authors, tags - x-markitect-source: loader metadata (auto-added) - Section classification validation (required, recommended, optional, discouraged, improper) - Content control pattern validation - Comprehensive documentation with examples and usage guides CLI Command (markitect schema-validate): - Validates schema files against metaschema - Supports both markdown and JSON schema files - Detailed error reporting with schema paths - Structure validation recommendations - Exit codes for CI/CD integration Test Coverage (tests/test_schema_metaschema.py - 12 tests, 100% passing): - Metaschema self-validation - Manpage schema validation - Required fields enforcement - Version format validation (valid and invalid cases) - $id format validation (valid and invalid cases) - Section classification validation - Complete schema with all extensions Validation Results: - ✅ Metaschema validates itself successfully - ✅ Manpage schema (v1.0.md) validates successfully - ⚠️ Terminology schema needs migration (missing version, incorrect $id) Progress Tracking: - Updated TODO.md with Phase 3 completion - Updated CHANGELOG.md with implementation details - Next: Phase 4 - Schema Migration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
9.5 KiB
9.5 KiB
Todofile
This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.
The format is based on Keep a Todofile V0.0.1.
The structure organizes future tasks by their impact, just as a changelog organizes past changes by their impact.
[Unreleased] - Active Vibe-Coding State 💡
This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.
Schema-of-Schemas Implementation (Active - Phase 3)
Status: Phase 3 - Schema-for-Schemas Metaschema (Completed ✅)
Workplan: See roadmap/schema-of-schemas/WORKPLAN.md
Current Goals:
- ✅ Establish naming convention:
{domain}-schema-v{major}.{minor}.md - ✅ Implement filename validation logic
- ✅ Create markdown schema loader
- ✅ Create example markdown schema
- ✅ Build schema-for-schemas metaschema
- ⏳ Migrate existing schemas to new format (Next: Phase 4)
Phase 1 Tasks (Completed ✅):
- Write
markitect/schema_naming.pywith validation logic - Add unit tests for filename validation (50 tests, 100% passing)
- Create SCHEMA_NAMING_SPEC.md documentation
Phase 2 Tasks (Completed ✅):
- Implement MarkdownSchemaLoader class (markitect/schema_loader.py, 515 lines)
- Add frontmatter extraction (YAML)
- Add JSON code block extraction with section preference
- Add metadata merging with x-markitect-source tracking
- Write comprehensive unit tests (35 tests, 100% passing)
- Create example markdown schema (manpage-schema-v1.0.md)
- Create SCHEMA_LOADER_GUIDE.md documentation
Phase 3 Tasks (Completed ✅):
- Design schema-for-schemas metaschema (schema-schema-v1.0.md)
- Implement metaschema with validation rules for MarkiTect conventions
- Add schema-validate CLI command with detailed error reporting
- Write comprehensive unit tests (12 tests, 100% passing)
- Test metaschema self-validation
- Validate existing schemas against metaschema
Next Phases:
- Phase 4: Schema Migration (1-2 days)
- Phase 5: CLI & Documentation Updates (1 day)
- Phase 6: Testing & Validation (1 day)
Expected Completion: 4-5 days remaining
Extract Capability-Capability from Issue-Facade (Paused)
Context: Issue-facade currently provides two capabilities:
- issue-tracking (explicit in CAPABILITY-issue-tracking.yaml) - Issue management across platforms
- capability-capability (implicit) - Patterns and tools for creating/managing capabilities
The capability-capability includes:
- Feedback pattern (feedback/ directory, .capability/feedback CLI tool, documentation)
- Detachment facility (.capability/detach script for clean capability removal)
- Integration pattern (.capability/integrate.sh for project integration)
- CAPABILITY-*.yaml specification format
- ReusableCapabilitiesArchitecture.md (complete specification)
- Directory conventions (_family/implementation, visible/hidden patterns)
Goal: Extract capability-capability to separate reusable-capability repository so it can be used by any capability in the markitect ecosystem.
Approach: Step-by-step extraction, starting with specification.
Phase 1: Specification & Planning (Current)
- Create CAPABILITY-capability.yaml in issue-facade to explicitly declare the implicit capability
- Define what belongs to capability-capability family vs issue-tracking family
- Document the capability-capability API surface (what tools/patterns it provides)
- Identify all files/directories to extract
- Plan extraction strategy (copy vs move, how to maintain during transition)
Phase 2: Repository Creation
- Create reusable-capability repository structure
- Extract ReusableCapabilitiesArchitecture.md to new repo
- Extract feedback pattern (directory structure, CLI tool, README)
- Extract detachment facility (.capability/detach)
- Extract integration scripts (.capability/integrate.sh, integration-checklist.md)
- Create CAPABILITY-capability.yaml in new repo (canonical version)
- Add README.md for reusable-capability repo
Phase 3: Integration & Testing
- Update issue-facade to depend on reusable-capability (as integrated capability)
- Integrate reusable-capability into issue-facade using _capability/reusable-capability pattern
- Test that issue-facade still works with extracted capability
- Update issue-facade documentation to reference both capabilities it provides/uses
- Verify feedback system still works
- Verify detachment still works
Phase 4: Dogfooding & Validation
- Choose another markitect capability for dogfooding
- Integrate reusable-capability into that capability
- Add feedback system to new capability
- Add detachment facility to new capability
- Document learnings and refine reusable-capability based on real-world usage
- Update ReusableCapabilitiesArchitecture.md with insights
Current Step: Phase 1, Task 1 - Create CAPABILITY-capability.yaml
Completed Tasks
Recent completed tasks have been documented in _issue-tracking/issue-facade/CHANGELOG.md following Keep a Changelog format.
2026-01-04 - Phase 2: Schema Refinement Tools & Terminology Example
- ✅ Implemented schema-analyze command to detect rigidity issues
- ✅ Implemented schema-refine command with automatic loosening logic
- ✅ Added interactive mode to schema-refine for fine-grained control
- ✅ Created comprehensive test suite (33 unit tests, 100% passing)
- ✅ Wrote user guide documentation with examples and workflows
- ✅ Successfully tested on example schemas (reduced rigidity from 60/100 to 24/100)
- ✅ Integrated into CLI with proper exit codes and error handling
- ✅ Moved SCHEMA_EVOLUTION_WORKPLAN.md to todo/ directory
- ✅ Created terminology validation example (examples/terminology/)
Key Features Delivered:
- Rigidity score calculation (0-100 scale)
- Automatic detection of exact counts, const values, overly specific numbers
- Path navigation for nested schema properties
- Dry-run mode for previewing changes
- Interactive approval workflow
- Comprehensive reporting (normal and verbose modes)
Terminology Example:
- Complete terminology document structure (terminology-example.md)
- JSON schema with MarkiTect extensions (terminology-schema.json)
- Demonstrates schema usage for non-manpage documents
- Validates term definitions, synonyms, related terms, examples
- Includes content control and validation rules
- Full documentation and usage examples (README.md)
2026-01-04 - Phase 2: Markdown Schema Loader
- ✅ Implemented MarkdownSchemaLoader class (markitect/schema_loader.py, 515 lines)
- ✅ YAML frontmatter extraction with validation
- ✅ JSON code block extraction with "Schema Definition" section preference
- ✅ Metadata merging with x-markitect-source tracking
- ✅ Schema saving with template support and round-trip capability
- ✅ Comprehensive test suite (35 unit tests, 100% passing)
- ✅ Created example markdown schema (manpage-schema-v1.0.md)
- ✅ Created SCHEMA_LOADER_GUIDE.md with complete usage documentation
Key Features Delivered:
- Markdown-first schema format with embedded JSON
- Frontmatter metadata merges into schema ($id, version, status)
- Automatic detection of multiple JSON blocks
- Schema structure validation helper
- Error handling for binary files and invalid formats
- List JSON blocks helper for debugging
- Full round-trip save/load capability
Example Markdown Schema:
- manpage-schema-v1.0.md demonstrating complete format
- Includes frontmatter, documentation, and JSON schema
- Shows section classification and content control
- Follows naming convention: {domain}-schema-v{major}.{minor}.md
2026-01-04 - Phase 3: Schema-for-Schemas Metaschema
- ✅ Created schema-schema-v1.0.md metaschema (650+ lines)
- ✅ Validates core JSON Schema fields ($schema, $id, title, description)
- ✅ Validates MarkiTect version field (SemVer: major.minor.patch)
- ✅ Validates $id URL format (HTTPS with version)
- ✅ Validates MarkiTect extensions (x-markitect-sections, x-markitect-content-control, x-markitect-metadata)
- ✅ Implemented schema-validate CLI command with detailed error reporting
- ✅ Comprehensive test suite (12 unit tests, 100% passing)
- ✅ Metaschema self-validation successful
Key Features Delivered:
- Complete metaschema for validating all MarkiTect schemas
- Section classification validation (required, recommended, optional, discouraged, improper)
- Content control pattern validation
- Version format enforcement (SemVer)
- $id URL format enforcement (HTTPS with version)
- CLI command for easy schema validation
- Detailed error messages with schema paths
Validation Results:
- ✅ Metaschema validates itself
- ✅ Manpage schema validates successfully
- ⚠️ Terminology schema needs migration (missing version field, incorrect $id format)
2025-12-17 - Architecture Refactoring
- ✅ Implemented ReusableCapabilitiesArchitecture v0.1
- ✅ Added feedback capability to issue-facade
- ✅ Created detachment facility
- ✅ Refactored to family-based directory structure (_issue-tracking/issue-facade)
- ✅ Made feedback directory visible (feedback/ not .feedback/)
- ✅ Renamed to explicit family declaration (CAPABILITY-issue-tracking.yaml)
- ✅ Created CHANGELOG.md documenting v1.0.0