7 Commits

Author	SHA1	Message	Date
tegwick	d32dc41315	docs: update manpage and terminology examples to schema-of-schemas standard ... 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>	2026-01-05 13:13:24 +01:00
tegwick	6df9b5df05	feat: add terminology schema example and improve schema-list command ... This commit completes Phase 2 of schema evolution work and establishes a new example demonstrating schema usage for terminology documents. ## New Features ### Terminology Validation Example (examples/terminology/) - Complete example terminology document with proper structure - JSON schema with MarkiTect extensions for validation - Demonstrates schema usage beyond manpages (glossaries, lexicons) - Validates term structure: Definition, Synonyms, Related Terms, Examples - Includes content control and quality validation rules - Full documentation with usage examples and best practices ### Schema Registration System - Registered terminology schema in markitect database - Created schema catalog (markitect/schemas/schema-catalog.yaml) - Copied schema to official location (markitect/schemas/) - Provides metadata, features, and usage info for all schemas ### Improved schema-list Command - Now displays creation timestamps in default output - Table format includes Created/Updated columns - Cleaner timestamp formatting (removed microseconds) - Better visibility into when schemas were added ## Files Changed Added: - examples/terminology/README.md - Complete documentation - examples/terminology/terminology-example.md - Example glossary - examples/terminology/terminology-schema.json - Validation schema - markitect/schemas/terminology-schema.json - Registered schema - markitect/schemas/schema-catalog.yaml - Schema registry Modified: - markitect/cli.py - Enhanced schema-list with timestamps - TODO.md - Documented Phase 2 completion and new example Moved: - SCHEMA_EVOLUTION_WORKPLAN.md → todo/ directory ## Schema Features Demonstrated - Heading hierarchy validation (H1 → H2 → H3) - Term structure validation with required/optional fields - Content quality metrics (word counts, readability targets) - MarkiTect extensions (x-markitect-sections, x-markitect-content-control) - Classification system (required/recommended/optional/discouraged/improper) ## Usage ```bash # List schemas with timestamps markitect schema-list # Validate terminology document markitect validate glossary.md --schema terminology-schema.json # View in table format markitect schema-list --format table ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-04 23:07:36 +01:00
tegwick	82c1a3ab65	docs: add OPTIONS section to schema validation manpage ... Added comprehensive OPTIONS section with 18 command-line options organized into 4 categories: 1. Validation Options (5 options) - --schema, --schema-json, --detailed-errors, --error-format, --quiet 2. Schema Generation Options (3 options) - --output, --style, --title 3. Schema Management Options (4 options) - --schema-list, --schema-info, --schema-delete, --confirm 4. Phase 2 Schema Refinement Options (6 options) - --verbose, --dry-run, --interactive, --loosen-counts, --round-numbers, --migrate-deprecated This addresses the schema recommendation: - Before: OPTIONS section missing (recommended but not present) - After: OPTIONS section present with 424 words, 22 documented options The manpage now fully complies with all schema recommendations: ✅ All required sections present (SYNOPSIS, DESCRIPTION) ✅ All recommended sections present (OPTIONS, EXAMPLES, SEE ALSO, COPYRIGHT) ✅ Document still validates successfully 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-04 21:49:03 +01:00
tegwick	c46d9f7a0b	docs: update schema validation manual with Phase 1 features ... Comprehensively document the new classification system and content control features added in Phase 1. ## Documentation Updates ### New Content Added **1. Updated MarkiTect Extensions Section** - Replaced deprecated x-markitect-required/recommended-sections - Documented x-markitect-sections with five classification levels - Documented x-markitect-content-control for content validation **2. Added Section Classification System (150+ lines)** - Detailed explanation of all five classification levels: - required: Missing = ERROR - recommended: Missing = WARNING - optional: No validation impact - discouraged: Present = WARNING - improper: Present = ERROR - Validation behavior for each classification - JSON examples for each level **3. Added Content Control Documentation** - Pattern validation (required/discouraged/forbidden) - Content quality metrics (word count, readability targets) - Content instructions for authors - Complete examples with explanations **4. Updated Schema Design Best Practices** - Replaced old extension examples with new classification system - Added guidance on choosing appropriate classifications - Examples showing required, recommended, optional, discouraged, improper **5. Added Classification System Example** - Complete working schema demonstrating all features - Validation scenarios showing different outcomes - Integration of sections and content-control extensions ## Changes Summary **Lines Added**: ~200 lines of new documentation **Sections Updated**: 4 major sections **Examples Added**: 8 new code examples **Key Topics Covered**: - Five-level classification system (required → improper) - Content pattern validation - Quality metrics and readability targets - Content instructions for document authors - Validation behavior for each classification - Complete working examples ## Validation ✅ Manual validates against improved markdown-manpage-schema.json ✅ All new features documented with examples ✅ Backward compatibility maintained ✅ Self-documenting: manual uses the features it documents The manual now comprehensively documents the Phase 1 enhanced schema system while itself validating against a schema using those features. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-04 21:20:27 +01:00
tegwick	2b687a4ca8	refactor: upgrade manpage schema to use new classification system ... Modernize the original markdown-manpage-schema.json to leverage Phase 1 classification features for improved flexibility and content guidance. ## Changes **Replaced old extension format:** ```json "x-markitect-required-sections": ["SYNOPSIS", "DESCRIPTION"], "x-markitect-recommended-sections": ["OPTIONS", "EXAMPLES"], "x-markitect-optional-sections": ["COMMANDS", "FILES"] ``` **With new classification system:** ```json "x-markitect-sections": { "SYNOPSIS": { "classification": "required", "heading_level": 2, "content_instruction": "...", "error_message": "..." } } ``` ## New Features Added **Section Classifications:** - 2 required: SYNOPSIS, DESCRIPTION - 4 recommended: OPTIONS, EXAMPLES, SEE ALSO, COPYRIGHT - 7 optional: COMMANDS, CONFIGURATION, FILES, EXIT STATUS, ENVIRONMENT, BUGS, AUTHORS **Content Control:** - Synopsis: Required patterns for command syntax, discouraged TODO/FIXME - Description: Quality metrics (50-1000 words), forbidden credential patterns - Examples: Required code blocks and comments **Enhanced Guidance:** - Per-section content instructions for authors - Custom error/warning messages - Alternative section names (e.g., OPTIONS | GLOBAL OPTIONS | FLAGS) - Content quality targets (word count, readability level) ## Validation ✅ Tested: markdown-schema-validation.1.md still validates successfully ✅ Backward compatible: Existing validation behavior preserved ✅ Enhanced: Now provides content guidance and flexible classifications This demonstrates the practical value of Phase 1 enhancements - the same schema now offers much richer validation and authoring guidance. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-04 21:09:34 +01:00
tegwick	d68e762612	feat: implement Phase 1 - Enhanced Schema Format with Classifications ... Complete Phase 1 of Schema Evolution Workplan implementing flexible content control and section classification system. ## New Features ### 1. x-markitect-sections Extension - Five classification levels: required, recommended, optional, discouraged, improper - Per-section content constraints (paragraphs, code blocks, lists) - Position hints for section ordering - Custom error/warning messages - Alternative section names support - Content instructions for authors ### 2. x-markitect-content-control Extension - Required/discouraged/forbidden pattern matching - Content quality metrics (word count, readability target, sentence count) - Content instruction arrays - Link validation configuration ### 3. Metaschema Validation - Updated markitect-metaschema.json with complete validation rules - Enhanced metaschema.py with validation methods for both extensions - Comprehensive validation of all extension properties - Clear error messages for invalid schemas ### 4. Documentation & Examples - Complete specification in docs/specifications/schema-extensions-spec.md - Enhanced manpage schema demonstrating all 5 classification levels - API documentation schema showing alternative patterns - Detailed usage examples and validation behavior ## Implementation Details **Files Modified:** - markitect/schemas/markitect-metaschema.json: Added extension definitions - markitect/metaschema.py: Added _validate_sections() and _validate_content_control() **Files Created:** - docs/specifications/schema-extensions-spec.md: Complete specification (v1.0) - examples/manpages/enhanced-manpage-schema.json: Demonstrates all classifications - examples/manpages/api-documentation-schema.json: Shows API doc patterns ## Validation Behavior **Classification Levels:** - required: Missing = ERROR (validation fails) - recommended: Missing = WARNING (validation succeeds with warnings) - optional: No validation impact - discouraged: Present = WARNING (validation succeeds with warnings) - improper: Present = ERROR (validation fails) ## Next Steps Phase 2: Schema Refinement Tools (schema-analyze, schema-refine, schema-compose) Phase 3: Enhanced Validation Engine (classification-aware validation, quality metrics) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-04 21:02:51 +01:00
tegwick	b51999582e	feat: add manpages example demonstrating schema validation ... Add comprehensive example showcasing schema validation with self-documenting manpage system: - markdown-manpage-schema.json: Reusable schema for Unix manpage structure - markdown-schema-validation.1.md: Complete manual about schema validation - README.md: Usage guide, integration examples, and best practices - SCHEMA_EVOLUTION_WORKPLAN.md: Roadmap for enhanced schema system The manual validates against its own schema, demonstrating dogfooding principle. Workplan outlines 5-phase evolution from rigid structural validation to flexible content control with blueprints. Key features demonstrated: - Schema-driven documentation structure - Self-validating documentation - Reusable validation patterns - Classification system design (required/recommended/optional/discouraged/improper) This sets foundation for Phase 1 implementation: enhanced schema format with section classification and content control. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-01-04 20:58:05 +01:00