diff --git a/CHANGELOG.md b/CHANGELOG.md index b81e42d2..c02f0fcd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ 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). +See roadmap/YYMMDD-ROADMAPTOPIC/ directories for planning information like concepts, workplans, etc... +See history/YYMMDD-ROADMAOTOPIC/ directories for planning information of closed topics + ## [Unreleased] ### Added diff --git a/TODO.md b/TODO.md index f58f345d..3e9db720 100644 --- a/TODO.md +++ b/TODO.md @@ -6,81 +6,14 @@ The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/Keep The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact. +See roadmap/YYMMDD-ROADMAPTOPIC/ directories for planning information like concepts, workplans, etc... + *** ## [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 4) - -**Status:** Completed (All 6 Phases ✅) -**Workplan:** See `history/2026-01-05-schema-of-schemas/WORKPLAN.md` (archived) - -**Current Goals:** -1. ✅ Establish naming convention: `{domain}-schema-v{major}.{minor}.md` -2. ✅ Implement filename validation logic -3. ✅ Create markdown schema loader -4. ✅ Create example markdown schema -5. ✅ Build schema-for-schemas metaschema -6. ✅ Migrate existing schemas to new format - -**Phase 1 Tasks (Completed ✅):** -- [x] Write `markitect/schema_naming.py` with validation logic -- [x] Add unit tests for filename validation (50 tests, 100% passing) -- [x] Create SCHEMA_NAMING_SPEC.md documentation - -**Phase 2 Tasks (Completed ✅):** -- [x] Implement MarkdownSchemaLoader class (markitect/schema_loader.py, 515 lines) -- [x] Add frontmatter extraction (YAML) -- [x] Add JSON code block extraction with section preference -- [x] Add metadata merging with x-markitect-source tracking -- [x] Write comprehensive unit tests (35 tests, 100% passing) -- [x] Create example markdown schema (manpage-schema-v1.0.md) -- [x] Create SCHEMA_LOADER_GUIDE.md documentation - -**Phase 3 Tasks (Completed ✅):** -- [x] Design schema-for-schemas metaschema (schema-schema-v1.0.md) -- [x] Implement metaschema with validation rules for MarkiTect conventions -- [x] Add schema-validate CLI command with detailed error reporting -- [x] Write comprehensive unit tests (12 tests, 100% passing) -- [x] Test metaschema self-validation -- [x] Validate existing schemas against metaschema - -**Phase 4 Tasks (Completed ✅):** -- [x] Create migration script (scripts/migrate_schemas.py) -- [x] Migrate terminology-schema.json → terminology-schema-v1.0.md -- [x] Migrate api-documentation → api-documentation-schema-v1.0.md -- [x] Delete duplicate schemas (markdown-manpage, markdown-manpage-schema.json) -- [x] Delete replaced schema (enhanced-manpage) -- [x] Update schema-ingest CLI to support markdown files -- [x] Validate all migrated schemas -- [x] Ingest all markdown schemas into database - -**Phase 5 Tasks (Completed ✅):** -- [x] Add numbered references to schema-list (all output formats) -- [x] Implement schema selection parser (numbers, ranges, lists) -- [x] Implement schema resolution logic (registry with filesystem fallback) -- [x] Enhance schema-validate command with multiple selection support -- [x] Add --all flag for batch validation -- [x] Implement batch output formatting with summary table -- [x] Test all selection methods (1, 1-3, 1,3,5, all, filename, ./path) -- [x] Maintain backward compatibility with single-file validation - -**Phase 6 Tasks (Completed ✅):** -- [x] Run complete test suite - all 97 tests passing (50 naming + 35 loader + 12 metaschema) -- [x] Perform end-to-end integration testing of complete schema workflow -- [x] Test schema creation, validation, ingestion, listing, and batch operations -- [x] Create comprehensive usage documentation (SCHEMA_MANAGEMENT_GUIDE.md) -- [x] Document all commands, workflows, and best practices -- [x] Verify no regressions in existing functionality - -**Schema-of-Schemas Implementation: COMPLETE ✅** - -All 6 phases completed successfully. The schema management system is fully functional with comprehensive testing and documentation. - ---- - ### Extract Capability-Capability from Issue-Facade (Paused) **Context:** Issue-facade currently provides two capabilities: @@ -137,164 +70,3 @@ The **capability-capability** includes: **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-05 - Phase 6: Integration Testing and Final Documentation -- ✅ Ran complete test suite - all 97 tests passing (50 naming + 35 loader + 12 metaschema) -- ✅ Performed end-to-end integration testing: - - Schema creation and validation - - Schema ingestion into registry - - Numbered schema listing - - Single schema validation (by number, filename, path) - - Batch validation (ranges, lists, --all) - - Schema deletion -- ✅ Created comprehensive SCHEMA_MANAGEMENT_GUIDE.md with: - - Quick start guide and templates - - Complete command reference - - Common workflows and examples - - Best practices and troubleshooting - - Advanced usage patterns - -**Schema-of-Schemas Implementation Complete:** -- 6 phases completed over 2 days -- 97 unit tests (100% passing) -- End-to-end integration verified -- Comprehensive documentation delivered -- Fully functional schema management system - -### 2026-01-05 - Phase 5: Enhanced Schema Validation with Multiple Selection -- ✅ Enhanced schema-list command with numbered references in all formats -- ✅ Implemented schema selection parser supporting: - - Single number: `markitect schema-validate 1` - - Number range: `markitect schema-validate 1-3` - - Number list: `markitect schema-validate 1,3,5` - - Keyword: `markitect schema-validate --all` or `all` - - Filename: `markitect schema-validate schema.md` - - Filesystem path: `markitect schema-validate ./schema.md` -- ✅ Implemented schema resolution with registry precedence and filesystem fallback -- ✅ Added batch validation with summary table output -- ✅ Added ValidationResult dataclass for structured results -- ✅ Created helper functions: parse_schema_selector, resolve_schema_source, is_filesystem_path, format_validation_summary -- ✅ Maintained full backward compatibility with existing single-file validation -- ✅ Tested all selection methods successfully - -**Key Features Delivered:** -- Number-based schema selection for quick validation -- Batch validation results displayed as clear summary table -- Registry schemas take precedence over filesystem paths -- Helpful error messages with usage examples -- Exit code 0 for success, 1 for validation failures -- Support for future wildcard/globbing expansion - -### 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) - -### 2026-01-05 - Phase 4: Schema Migration -- ✅ Created migration script (scripts/migrate_schemas.py, 240 lines) -- ✅ Migrated 2 schemas to markdown format -- ✅ Deleted 3 duplicate/replaced schemas from database -- ✅ Updated schema-ingest CLI to support markdown files (.md) -- ✅ All 4 schemas now in markdown format following naming convention - -**Schemas Migrated:** -- terminology-schema.json → terminology-schema-v1.0.md -- api-documentation → api-documentation-schema-v1.0.md - -**Schemas Deleted:** -- markdown-manpage (duplicate) -- markdown-manpage-schema.json (duplicate) -- enhanced-manpage (replaced by manpage-schema-v1.0.md) - -**Final Schema Registry:** -- ✅ terminology-schema-v1.0.md -- ✅ api-documentation-schema-v1.0.md -- ✅ manpage-schema-v1.0.md -- ✅ schema-schema-v1.0.md (metaschema) - -All schemas validate successfully against the metaschema! - -### 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 diff --git a/history/2025/251217-DONE.md b/history/2025/251217-DONE.md new file mode 100644 index 00000000..74f67b08 --- /dev/null +++ b/history/2025/251217-DONE.md @@ -0,0 +1,13 @@ +# Donefile + +This was a "to do next" file for the roadmap topic and has been archived on closing the topic. + + +### 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 diff --git a/history/260105-schema-of-schemas/260105-DONE.md b/history/260105-schema-of-schemas/260105-DONE.md new file mode 100644 index 00000000..195742ae --- /dev/null +++ b/history/260105-schema-of-schemas/260105-DONE.md @@ -0,0 +1,222 @@ +# Donefile + +This was a "to do next" file for the roadmap topic and has been archived on closing the topic. + +### Schema-of-Schemas Implementation (Active - Phase 4) + +**Status:** Completed (All 6 Phases ✅) +**Workplan:** See `history/2026-01-05-schema-of-schemas/WORKPLAN.md` (archived) + +**Current Goals:** +1. ✅ Establish naming convention: `{domain}-schema-v{major}.{minor}.md` +2. ✅ Implement filename validation logic +3. ✅ Create markdown schema loader +4. ✅ Create example markdown schema +5. ✅ Build schema-for-schemas metaschema +6. ✅ Migrate existing schemas to new format + +**Phase 1 Tasks (Completed ✅):** +- [x] Write `markitect/schema_naming.py` with validation logic +- [x] Add unit tests for filename validation (50 tests, 100% passing) +- [x] Create SCHEMA_NAMING_SPEC.md documentation + +**Phase 2 Tasks (Completed ✅):** +- [x] Implement MarkdownSchemaLoader class (markitect/schema_loader.py, 515 lines) +- [x] Add frontmatter extraction (YAML) +- [x] Add JSON code block extraction with section preference +- [x] Add metadata merging with x-markitect-source tracking +- [x] Write comprehensive unit tests (35 tests, 100% passing) +- [x] Create example markdown schema (manpage-schema-v1.0.md) +- [x] Create SCHEMA_LOADER_GUIDE.md documentation + +**Phase 3 Tasks (Completed ✅):** +- [x] Design schema-for-schemas metaschema (schema-schema-v1.0.md) +- [x] Implement metaschema with validation rules for MarkiTect conventions +- [x] Add schema-validate CLI command with detailed error reporting +- [x] Write comprehensive unit tests (12 tests, 100% passing) +- [x] Test metaschema self-validation +- [x] Validate existing schemas against metaschema + +**Phase 4 Tasks (Completed ✅):** +- [x] Create migration script (scripts/migrate_schemas.py) +- [x] Migrate terminology-schema.json → terminology-schema-v1.0.md +- [x] Migrate api-documentation → api-documentation-schema-v1.0.md +- [x] Delete duplicate schemas (markdown-manpage, markdown-manpage-schema.json) +- [x] Delete replaced schema (enhanced-manpage) +- [x] Update schema-ingest CLI to support markdown files +- [x] Validate all migrated schemas +- [x] Ingest all markdown schemas into database + +**Phase 5 Tasks (Completed ✅):** +- [x] Add numbered references to schema-list (all output formats) +- [x] Implement schema selection parser (numbers, ranges, lists) +- [x] Implement schema resolution logic (registry with filesystem fallback) +- [x] Enhance schema-validate command with multiple selection support +- [x] Add --all flag for batch validation +- [x] Implement batch output formatting with summary table +- [x] Test all selection methods (1, 1-3, 1,3,5, all, filename, ./path) +- [x] Maintain backward compatibility with single-file validation + +**Phase 6 Tasks (Completed ✅):** +- [x] Run complete test suite - all 97 tests passing (50 naming + 35 loader + 12 metaschema) +- [x] Perform end-to-end integration testing of complete schema workflow +- [x] Test schema creation, validation, ingestion, listing, and batch operations +- [x] Create comprehensive usage documentation (SCHEMA_MANAGEMENT_GUIDE.md) +- [x] Document all commands, workflows, and best practices +- [x] Verify no regressions in existing functionality + +**Schema-of-Schemas Implementation: COMPLETE ✅** + +All 6 phases completed successfully. The schema management system is fully functional with comprehensive testing and documentation. + +## Completed Tasks + +*Recent completed tasks have been documented in _issue-tracking/issue-facade/CHANGELOG.md following Keep a Changelog format.* + +### 2026-01-05 - Phase 6: Integration Testing and Final Documentation +- ✅ Ran complete test suite - all 97 tests passing (50 naming + 35 loader + 12 metaschema) +- ✅ Performed end-to-end integration testing: + - Schema creation and validation + - Schema ingestion into registry + - Numbered schema listing + - Single schema validation (by number, filename, path) + - Batch validation (ranges, lists, --all) + - Schema deletion +- ✅ Created comprehensive SCHEMA_MANAGEMENT_GUIDE.md with: + - Quick start guide and templates + - Complete command reference + - Common workflows and examples + - Best practices and troubleshooting + - Advanced usage patterns + +**Schema-of-Schemas Implementation Complete:** +- 6 phases completed over 2 days +- 97 unit tests (100% passing) +- End-to-end integration verified +- Comprehensive documentation delivered +- Fully functional schema management system + +### 2026-01-05 - Phase 5: Enhanced Schema Validation with Multiple Selection +- ✅ Enhanced schema-list command with numbered references in all formats +- ✅ Implemented schema selection parser supporting: + - Single number: `markitect schema-validate 1` + - Number range: `markitect schema-validate 1-3` + - Number list: `markitect schema-validate 1,3,5` + - Keyword: `markitect schema-validate --all` or `all` + - Filename: `markitect schema-validate schema.md` + - Filesystem path: `markitect schema-validate ./schema.md` +- ✅ Implemented schema resolution with registry precedence and filesystem fallback +- ✅ Added batch validation with summary table output +- ✅ Added ValidationResult dataclass for structured results +- ✅ Created helper functions: parse_schema_selector, resolve_schema_source, is_filesystem_path, format_validation_summary +- ✅ Maintained full backward compatibility with existing single-file validation +- ✅ Tested all selection methods successfully + +**Key Features Delivered:** +- Number-based schema selection for quick validation +- Batch validation results displayed as clear summary table +- Registry schemas take precedence over filesystem paths +- Helpful error messages with usage examples +- Exit code 0 for success, 1 for validation failures +- Support for future wildcard/globbing expansion + +### 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) + +### 2026-01-05 - Phase 4: Schema Migration +- ✅ Created migration script (scripts/migrate_schemas.py, 240 lines) +- ✅ Migrated 2 schemas to markdown format +- ✅ Deleted 3 duplicate/replaced schemas from database +- ✅ Updated schema-ingest CLI to support markdown files (.md) +- ✅ All 4 schemas now in markdown format following naming convention + +**Schemas Migrated:** +- terminology-schema.json → terminology-schema-v1.0.md +- api-documentation → api-documentation-schema-v1.0.md + +**Schemas Deleted:** +- markdown-manpage (duplicate) +- markdown-manpage-schema.json (duplicate) +- enhanced-manpage (replaced by manpage-schema-v1.0.md) + +**Final Schema Registry:** +- ✅ terminology-schema-v1.0.md +- ✅ api-documentation-schema-v1.0.md +- ✅ manpage-schema-v1.0.md +- ✅ schema-schema-v1.0.md (metaschema) + +All schemas validate successfully against the metaschema! + diff --git a/history/README.md b/history/README.md index a3a51882..a3a325cc 100644 --- a/history/README.md +++ b/history/README.md @@ -2,8 +2,8 @@ This history directory contains old planning directories for roadmap topics. - Content of former years will be pushed to YYYY subdirectory for ease of orientation -- 2025 has not been using using topic directories but various files. -- See the roadmap directory for current and future topics. +- See ../roadmap for current and future topics +- 2025 has not been using using topic directories but various files ## Purpose diff --git a/roadmap/schema-evolution/SCHEMA_EVOLUTION_WORKPLAN.md b/roadmap/260105-schema-evolution/SCHEMA_EVOLUTION_WORKPLAN.md similarity index 100% rename from roadmap/schema-evolution/SCHEMA_EVOLUTION_WORKPLAN.md rename to roadmap/260105-schema-evolution/SCHEMA_EVOLUTION_WORKPLAN.md diff --git a/roadmap/README.md b/roadmap/README.md new file mode 100644 index 00000000..e372e588 --- /dev/null +++ b/roadmap/README.md @@ -0,0 +1,18 @@ +# MarkiTect Project Roadmap + +This roadmap directory contains planning directories for roadmap topics. +- When starting to implement a topic its directory will be timestamped +- If implementing multiple topics in parallel use branches +- Keep current state of what's next to implement in TODO.md +- See ../history directory for closed topics + +## Purpose + +This planning documentation serves multiple purposes: + +1. **Implementation State Awareness**: Allow for recovery after breaks or breakdowns +2. **Minimal Plan-Implement Loop**: Don't complicate agentic coding with issue tracking if unnecessary +3. **Planning Info Analysis**: Keeping the planning info allows for retrospective analyses to optimize +4. **Clean Repo Structure**: Using roadmap/ for planning and TODO.md as current state helps stay organized + +xxx