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
parent 82c1a3ab65
commit 6df9b5df05
8 changed files with 927 additions and 3 deletions
--- a/TODO.md
+++ b/TODO.md
@@ -76,7 +76,7 @@ The **capability-capability** includes:

 *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
+### 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
@@ -84,6 +84,8 @@ The **capability-capability** includes:
 - ✅ 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)
@@ -93,6 +95,14 @@ The **capability-capability** includes:
 - 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)
+
 ### 2025-12-17 - Architecture Refactoring
 - ✅ Implemented ReusableCapabilitiesArchitecture v0.1
 - ✅ Added feedback capability to issue-facade
--- a/examples/terminology/README.md
+++ b/examples/terminology/README.md
@@ -0,0 +1,287 @@
+# Terminology Document Example
+
+This example demonstrates how to use MarkiTect schemas to validate terminology and glossary documents.
+
+## Overview
+
+Terminology documents (glossaries, dictionaries, lexicons) benefit from consistent structure and validation. This example shows how to:
+
+1. Structure terminology documents with clear categories and term definitions
+2. Validate terminology documents using JSON schemas
+3. Use MarkiTect's schema extensions for content control
+
+## Files
+
+- **terminology-example.md** - Example terminology document with proper structure
+- **terminology-schema.json** - JSON schema for validating terminology documents
+- **README.md** - This file
+
+## Terminology Document Structure
+
+A well-structured terminology document includes:
+
+### Required Elements
+
+1. **Main Title (Level 1 Heading)**
+   - Should include keywords: "Terminology", "Glossary", "Terms", or "Definitions"
+
+2. **Category Sections (Level 2 Headings)**
+   - Organize terms into logical groups
+   - Examples: "Core Concepts", "Document Types", "Process Terms"
+
+3. **Term Definitions (Level 3 Headings)**
+   - Each term as a level 3 heading
+   - Followed by structured content
+
+### Term Structure
+
+Each term should include:
+
+**Required:**
+- **Definition:** Clear, concise explanation of the term
+
+**Optional (but recommended):**
+- **Synonyms:** Alternative names or abbreviations
+- **Related Terms:** Links to related concepts
+- **Example:** Practical usage example
+- **Use Cases:** Common scenarios
+- **Format:** For document type terms
+- **Components:** For complex concepts
+- **Steps:** For process terms
+
+## Usage
+
+### Using the Registered Schema
+
+The terminology schema is registered in markitect's database and can be used by name:
+
+```bash
+# List all registered schemas (terminology-schema.json should appear)
+markitect schema-list
+
+# Validate using the registered schema
+markitect validate my-glossary.md --schema terminology-schema.json
+
+# Or use the local file directly
+markitect validate my-glossary.md --schema examples/terminology/terminology-schema.json
+```
+
+### Validate with Detailed Errors
+
+```bash
+markitect validate my-glossary.md --schema terminology-schema.json --detailed-errors
+```
+
+### Register the Schema (if needed)
+
+If the schema isn't already registered, you can add it to markitect's database:
+
+```bash
+markitect schema-ingest markitect/schemas/terminology-schema.json
+```
+
+### Generate Schema from Example
+
+```bash
+markitect schema-generate terminology-example.md --output my-terminology-schema.json
+```
+
+## Schema Features
+
+This schema demonstrates several MarkiTect features:
+
+### 1. Structural Validation
+
+- Enforces consistent heading hierarchy (H1 → H2 → H3)
+- Validates minimum term count
+- Ensures proper document structure
+
+### 2. Content Pattern Validation
+
+- Validates title pattern (must contain terminology-related keywords)
+- Checks for required field labels (Definition:, Synonyms:, etc.)
+- Enforces consistent formatting
+
+### 3. MarkiTect Extensions
+
+The schema uses MarkiTect-specific extensions:
+
+#### `x-markitect-sections`
+Defines section classifications and requirements:
+- `document_title` (required)
+- `category_sections` (required, min 1)
+- `term_definitions` (required, min 1)
+
+#### `x-markitect-content-control`
+Specifies content requirements:
+- Required vs optional components
+- Content quality metrics (word counts)
+- Content instructions for authors
+
+#### `x-markitect-validation-rules`
+Custom validation rules:
+- Minimum term count (3 required, 10+ recommended)
+- Category balance (min 2 terms per category)
+- Definition quality checks
+- Consistency validation
+
+## Best Practices
+
+### 1. Use Consistent Field Labels
+
+Always use the same labels for metadata:
+```markdown
+**Definition:** ...
+**Synonyms:** ...
+**Related Terms:** ...
+```
+
+### 2. Write Clear Definitions
+
+- Start with the term's primary meaning
+- Use 10-200 words
+- Be self-contained (don't require reading other terms)
+- Avoid circular definitions
+
+### 3. Group Related Terms
+
+Organize terms into logical categories:
+- Core Concepts
+- Document Types
+- Process Terms
+- Quality Attributes
+- Deprecated Terms
+
+### 4. Include Examples
+
+Add practical examples for complex terms:
+```markdown
+**Example:**
+\`\`\`markdown
+# Heading
+Paragraph text
+\`\`\`
+```
+
+### 5. Link Related Terms
+
+Use **Related Terms:** to create a terminology graph:
+```markdown
+**Related Terms:** Parser, Token, Node
+```
+
+## Extending the Schema
+
+You can customize the schema for your project:
+
+### Add Custom Field Labels
+
+Extend the `bold_text` enum:
+```json
+"enum": [
+  "Definition:",
+  "Synonyms:",
+  "Your Custom Label:"
+]
+```
+
+### Adjust Quality Metrics
+
+Modify content quality requirements:
+```json
+"content_quality": {
+  "min_words_per_definition": 20,
+  "max_words_per_definition": 300,
+  "readability_target": "business"
+}
+```
+
+### Add Domain-Specific Validation
+
+Include specialized validation rules:
+```json
+"x-markitect-validation-rules": {
+  "domain_specific": {
+    "require_acronym_expansion": true,
+    "require_source_citations": true
+  }
+}
+```
+
+## Use Cases
+
+### Documentation Projects
+
+- Software project glossaries
+- API terminology reference
+- Architecture decision records (ADR) glossary
+- Domain-driven design (DDD) ubiquitous language
+
+### Technical Writing
+
+- Standards documentation
+- Compliance documentation (ISO, SOC2)
+- Technical specifications
+- Research papers
+
+### Knowledge Management
+
+- Company wikis
+- Team handbooks
+- Onboarding documentation
+- Training materials
+
+## Integration with CI/CD
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+markitect validate docs/glossary.md --schema schemas/terminology-schema.json
+```
+
+### GitHub Actions
+
+```yaml
+name: Validate Terminology
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install MarkiTect
+        run: pip install markitect
+      - name: Validate Glossary
+        run: |
+          markitect validate docs/glossary.md \
+            --schema schemas/terminology-schema.json \
+            --detailed-errors
+```
+
+## Related Examples
+
+- **manpages/** - Manual page documentation validation
+- **templates/** - Document template examples
+- **design-patterns/** - Software pattern documentation
+
+## Learn More
+
+- [Schema Extensions Specification](../../docs/specifications/schema-extensions-spec.md)
+- [MarkiTect Documentation](../../README.md)
+- [JSON Schema Documentation](https://json-schema.org/)
+
+## Contributing
+
+To improve this example:
+
+1. Add more terms to demonstrate edge cases
+2. Enhance the schema with additional validation rules
+3. Create alternative terminology document styles
+4. Add multilingual terminology examples
+
+## License
+
+This example is part of the MarkiTect project and follows the same license.
--- a/examples/terminology/terminology-example.md
+++ b/examples/terminology/terminology-example.md
@@ -0,0 +1,91 @@
+# Project Terminology
+
+A glossary of key terms and concepts for this project.
+
+## Core Concepts
+
+### Abstract Syntax Tree
+
+**Definition:** A tree representation of the abstract syntactic structure of source code or markup, where each node represents a construct occurring in the source.
+
+**Synonyms:** AST, Parse Tree
+
+**Related Terms:** Parser, Token, Node
+
+**Example:**
+```markdown
+# Heading
+Paragraph text
+```
+
+The AST representation would include nodes for heading (level 1) and paragraph elements.
+
+### Schema Validation
+
+**Definition:** The process of verifying that a document's structure conforms to a predefined schema specification.
+
+**Synonyms:** Structural Validation, Schema Conformance
+
+**Related Terms:** JSON Schema, Validator, Metaschema
+
+**Use Cases:**
+- Ensuring documentation completeness
+- Enforcing content standards
+- Automated quality checks
+
+## Document Types
+
+### Manpage
+
+**Definition:** A manual page document following Unix/Linux documentation conventions, typically including sections like SYNOPSIS, DESCRIPTION, and OPTIONS.
+
+**Format:** Markdown with specific heading structure
+
+**Related Terms:** Documentation, Manual, Help Text
+
+### Blueprint
+
+**Definition:** A template specification that combines schemas, content instructions, and data templates for generating documents.
+
+**Components:**
+- Schema references
+- Content model
+- Data schema
+- Generation rules
+
+## Process Terms
+
+### Schema Refinement
+
+**Definition:** The process of transforming a rigid, auto-generated schema into a flexible, classification-aware schema with content guidance.
+
+**Steps:**
+1. Analyze existing schema for rigidity
+2. Loosen exact constraints to ranges
+3. Add classification metadata
+4. Include content instructions
+
+**Tools:** `markitect schema-analyze`, `markitect schema-refine`
+
+## Quality Attributes
+
+### Classification Levels
+
+**Definition:** A hierarchical system for categorizing document elements based on their importance and requirements.
+
+**Levels:**
+- **Required**: Must be present (validation fails if missing)
+- **Recommended**: Should be present (warning if missing)
+- **Optional**: May be present (no impact)
+- **Discouraged**: Should not be present (warning if present)
+- **Improper**: Must not be present (validation fails if present)
+
+## Deprecated Terms
+
+### Rigid Schema
+
+**Status:** DEPRECATED - Use "Unrefined Schema" instead
+
+**Definition:** A schema with exact count constraints that make it unusable as a pattern.
+
+**Migration:** Use schema refinement tools to convert to flexible schemas.
--- a/examples/terminology/terminology-schema.json
+++ b/examples/terminology/terminology-schema.json
@@ -0,0 +1,214 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/terminology-v1.json",
+  "title": "Terminology Document Schema",
+  "description": "Schema for validating terminology and glossary documents with consistent structure",
+  "type": "object",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Main document title",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Category headings (Core Concepts, Document Types, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 20
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Individual term headings",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Term name - should be title case"
+              }
+            }
+          },
+          "minItems": 1
+        }
+      },
+      "required": ["level_1", "level_2", "level_3"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Content paragraphs including definitions and descriptions",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "minLength": 10
+          }
+        }
+      },
+      "minItems": 3
+    },
+    "bold_text": {
+      "type": "array",
+      "description": "Bold text used for field labels (Definition, Synonyms, etc.)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "enum": [
+              "Definition:",
+              "Synonyms:",
+              "Related Terms:",
+              "Example:",
+              "Examples:",
+              "Use Cases:",
+              "Usage:",
+              "Format:",
+              "Components:",
+              "Steps:",
+              "Tools:",
+              "Levels:",
+              "Status:",
+              "Migration:",
+              "Required:",
+              "Recommended:",
+              "Optional:",
+              "Discouraged:",
+              "Improper:"
+            ]
+          }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["headings", "paragraphs"],
+  "x-markitect-sections": {
+    "document_title": {
+      "classification": "required",
+      "heading_level": 1,
+      "content_instruction": "Main title should include words like 'Terminology', 'Glossary', or 'Definitions'",
+      "pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
+    },
+    "category_sections": {
+      "classification": "required",
+      "heading_level": 2,
+      "min_sections": 1,
+      "content_instruction": "Organize terms into logical categories (e.g., Core Concepts, Document Types, Process Terms)"
+    },
+    "term_definitions": {
+      "classification": "required",
+      "heading_level": 3,
+      "min_sections": 1,
+      "content_instruction": "Each term should be a level 3 heading followed by its definition and optional metadata"
+    }
+  },
+  "x-markitect-content-control": {
+    "term_structure": {
+      "required_components": [
+        {
+          "label": "Definition:",
+          "type": "bold_text",
+          "description": "Clear, concise definition of the term"
+        }
+      ],
+      "optional_components": [
+        {
+          "label": "Synonyms:",
+          "type": "bold_text",
+          "description": "Alternative names or abbreviations"
+        },
+        {
+          "label": "Related Terms:",
+          "type": "bold_text",
+          "description": "Links to related concepts"
+        },
+        {
+          "label": "Example:",
+          "type": "bold_text_or_code",
+          "description": "Practical example demonstrating the term"
+        },
+        {
+          "label": "Use Cases:",
+          "type": "list",
+          "description": "Common scenarios where term applies"
+        }
+      ],
+      "content_quality": {
+        "min_words_per_definition": 10,
+        "max_words_per_definition": 200,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Start each term with a level 3 heading containing the term name",
+        "Follow immediately with 'Definition:' in bold",
+        "Provide a clear, self-contained definition",
+        "Add optional fields (Synonyms, Related Terms, Examples) as needed",
+        "Use consistent formatting across all terms",
+        "Group related terms under category headings (level 2)"
+      ]
+    },
+    "definition_pattern": {
+      "description": "Each definition should follow: Term heading (###) → Definition: (bold) → Definition text",
+      "validation": {
+        "heading_level_3_followed_by": "bold_text_starting_with_Definition",
+        "definition_length": {
+          "min_words": 10,
+          "max_words": 200
+        }
+      }
+    },
+    "deprecated_terms": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Optional section for deprecated terms with migration guidance",
+      "required_fields": [
+        "Status: DEPRECATED",
+        "Migration:"
+      ]
+    }
+  },
+  "x-markitect-validation-rules": {
+    "term_count": {
+      "min": 3,
+      "recommended_min": 10,
+      "description": "Terminology document should define at least 3 terms, 10+ recommended"
+    },
+    "category_balance": {
+      "description": "Each category should have at least 2 terms",
+      "min_terms_per_category": 2
+    },
+    "definition_quality": {
+      "all_terms_must_have_definition": true,
+      "definition_must_follow_term_heading": true,
+      "definition_min_words": 10
+    },
+    "consistency": {
+      "use_consistent_field_labels": true,
+      "maintain_heading_hierarchy": true
+    }
+  }
+}
--- a/markitect/cli.py
+++ b/markitect/cli.py
@@ -1740,15 +1740,46 @@ def schema_list(config, output_format, names_only):
            click.echo()

            for schema_info in schemas:
-                click.echo(f"🔧 {schema_info['filename']}")
+                # Format timestamp for display (remove microseconds)
+                created = schema_info['created_at']
+                if created:
+                    # Format: YYYY-MM-DD HH:MM:SS (remove microseconds if present)
+                    if '.' in created:
+                        created_display = created.split('.')[0]
+                    else:
+                        created_display = created
+                    click.echo(f"🔧 {schema_info['filename']:<40} (added: {created_display})")
+                else:
+                    click.echo(f"🔧 {schema_info['filename']}")
+
                if config.get('verbose'):
                    click.echo(f"   Title: {schema_info['title']}")
                    click.echo(f"   Created: {schema_info['created_at']}")
+                    click.echo(f"   Updated: {schema_info['updated_at']}")
                    if schema_info['description']:
                        click.echo(f"   Description: {schema_info['description']}")
                    click.echo()
+        elif output_format == 'table':
+            # Custom table format for better readability
+            table_data = []
+            for schema in schemas:
+                # Format timestamps (remove microseconds)
+                created_date = schema['created_at'].split('.')[0] if schema['created_at'] and '.' in schema['created_at'] else schema['created_at']
+                updated_date = schema['updated_at'].split('.')[0] if schema['updated_at'] and '.' in schema['updated_at'] else schema['updated_at']
+
+                table_data.append({
+                    'Name': schema['filename'],
+                    'Title': schema['title'] or '',
+                    'Created': created_date or '',
+                    'Updated': updated_date or ''
+                })
+
+            if table_data:
+                headers = ['Name', 'Title', 'Created', 'Updated']
+                rows = [[row[h] for h in headers] for row in table_data]
+                click.echo(tabulate(rows, headers=headers, tablefmt='simple'))
        else:
-            # Use structured format (table, json, yaml)
+            # Use structured format (json, yaml)
            formatted_output = format_output(schemas, output_format)
            click.echo(formatted_output)

--- a/markitect/schemas/schema-catalog.yaml
+++ b/markitect/schemas/schema-catalog.yaml
@@ -0,0 +1,77 @@
+# MarkiTect Schema Catalog
+#
+# This catalog provides metadata about available schemas for markdown document validation.
+# Schemas can be referenced by name or loaded from their file path.
+
+version: "1.0"
+description: "Catalog of registered MarkiTect schemas for document validation"
+
+schemas:
+  - id: "markitect-metaschema"
+    name: "MarkiTect Metaschema"
+    file: "markitect-metaschema.json"
+    version: "1.0"
+    description: "Metaschema for validating MarkiTect schema extensions"
+    type: "metaschema"
+    usage: "Used internally to validate schema files with MarkiTect-specific extensions"
+    tags:
+      - internal
+      - validation
+      - metaschema
+
+  - id: "terminology-v1"
+    name: "Terminology Document Schema"
+    file: "terminology-schema.json"
+    version: "1.0"
+    description: "Schema for validating terminology and glossary documents"
+    type: "document-schema"
+    usage: "Validates technical glossaries, terminology documents, and definition lists"
+    document_types:
+      - glossary
+      - terminology
+      - lexicon
+      - dictionary
+    features:
+      - Heading hierarchy validation (H1 → H2 → H3)
+      - Term structure validation (Definition, Synonyms, Related Terms, etc.)
+      - Content quality metrics (word counts, readability)
+      - MarkiTect extensions (x-markitect-sections, x-markitect-content-control)
+      - Classification system (required/recommended/optional)
+    example: "examples/terminology/terminology-example.md"
+    tags:
+      - documentation
+      - glossary
+      - terminology
+      - definitions
+    related_schemas: []
+    author: "MarkiTect Project"
+    created: "2026-01-04"
+    updated: "2026-01-04"
+
+# Future schemas to add:
+#
+# - id: "manpage-v1"
+#   name: "Unix Manual Page Schema"
+#   description: "Schema for Unix/Linux manual page documentation"
+#
+# - id: "api-reference-v1"
+#   name: "API Reference Schema"
+#   description: "Schema for API endpoint documentation"
+#
+# - id: "arc42-v1"
+#   name: "arc42 Architecture Documentation Schema"
+#   description: "Schema for arc42 architecture documentation template"
+#
+# - id: "adr-v1"
+#   name: "Architecture Decision Record Schema"
+#   description: "Schema for ADR (Architecture Decision Record) documents"
+#
+# - id: "rfc-v1"
+#   name: "RFC/Specification Schema"
+#   description: "Schema for RFC-style specification documents"
+
+# Schema discovery paths:
+# - Built-in: markitect/schemas/*.json
+# - User-defined: ~/.markitect/schemas/*.json
+# - Project-specific: .markitect/schemas/*.json
+# - Custom paths via MARKITECT_SCHEMA_PATH environment variable
--- a/markitect/schemas/terminology-schema.json
+++ b/markitect/schemas/terminology-schema.json
@@ -0,0 +1,214 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/terminology-v1.json",
+  "title": "Terminology Document Schema",
+  "description": "Schema for validating terminology and glossary documents with consistent structure",
+  "type": "object",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Main document title",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Category headings (Core Concepts, Document Types, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 20
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Individual term headings",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Term name - should be title case"
+              }
+            }
+          },
+          "minItems": 1
+        }
+      },
+      "required": ["level_1", "level_2", "level_3"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Content paragraphs including definitions and descriptions",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "minLength": 10
+          }
+        }
+      },
+      "minItems": 3
+    },
+    "bold_text": {
+      "type": "array",
+      "description": "Bold text used for field labels (Definition, Synonyms, etc.)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "enum": [
+              "Definition:",
+              "Synonyms:",
+              "Related Terms:",
+              "Example:",
+              "Examples:",
+              "Use Cases:",
+              "Usage:",
+              "Format:",
+              "Components:",
+              "Steps:",
+              "Tools:",
+              "Levels:",
+              "Status:",
+              "Migration:",
+              "Required:",
+              "Recommended:",
+              "Optional:",
+              "Discouraged:",
+              "Improper:"
+            ]
+          }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["headings", "paragraphs"],
+  "x-markitect-sections": {
+    "document_title": {
+      "classification": "required",
+      "heading_level": 1,
+      "content_instruction": "Main title should include words like 'Terminology', 'Glossary', or 'Definitions'",
+      "pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
+    },
+    "category_sections": {
+      "classification": "required",
+      "heading_level": 2,
+      "min_sections": 1,
+      "content_instruction": "Organize terms into logical categories (e.g., Core Concepts, Document Types, Process Terms)"
+    },
+    "term_definitions": {
+      "classification": "required",
+      "heading_level": 3,
+      "min_sections": 1,
+      "content_instruction": "Each term should be a level 3 heading followed by its definition and optional metadata"
+    }
+  },
+  "x-markitect-content-control": {
+    "term_structure": {
+      "required_components": [
+        {
+          "label": "Definition:",
+          "type": "bold_text",
+          "description": "Clear, concise definition of the term"
+        }
+      ],
+      "optional_components": [
+        {
+          "label": "Synonyms:",
+          "type": "bold_text",
+          "description": "Alternative names or abbreviations"
+        },
+        {
+          "label": "Related Terms:",
+          "type": "bold_text",
+          "description": "Links to related concepts"
+        },
+        {
+          "label": "Example:",
+          "type": "bold_text_or_code",
+          "description": "Practical example demonstrating the term"
+        },
+        {
+          "label": "Use Cases:",
+          "type": "list",
+          "description": "Common scenarios where term applies"
+        }
+      ],
+      "content_quality": {
+        "min_words_per_definition": 10,
+        "max_words_per_definition": 200,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Start each term with a level 3 heading containing the term name",
+        "Follow immediately with 'Definition:' in bold",
+        "Provide a clear, self-contained definition",
+        "Add optional fields (Synonyms, Related Terms, Examples) as needed",
+        "Use consistent formatting across all terms",
+        "Group related terms under category headings (level 2)"
+      ]
+    },
+    "definition_pattern": {
+      "description": "Each definition should follow: Term heading (###) → Definition: (bold) → Definition text",
+      "validation": {
+        "heading_level_3_followed_by": "bold_text_starting_with_Definition",
+        "definition_length": {
+          "min_words": 10,
+          "max_words": 200
+        }
+      }
+    },
+    "deprecated_terms": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Optional section for deprecated terms with migration guidance",
+      "required_fields": [
+        "Status: DEPRECATED",
+        "Migration:"
+      ]
+    }
+  },
+  "x-markitect-validation-rules": {
+    "term_count": {
+      "min": 3,
+      "recommended_min": 10,
+      "description": "Terminology document should define at least 3 terms, 10+ recommended"
+    },
+    "category_balance": {
+      "description": "Each category should have at least 2 terms",
+      "min_terms_per_category": 2
+    },
+    "definition_quality": {
+      "all_terms_must_have_definition": true,
+      "definition_must_follow_term_heading": true,
+      "definition_min_words": 10
+    },
+    "consistency": {
+      "use_consistent_field_labels": true,
+      "maintain_heading_hierarchy": true
+    }
+  }
+}
--- a/examples/manpages/SCHEMA_EVOLUTION_WORKPLAN.md
+++ b/examples/manpages/SCHEMA_EVOLUTION_WORKPLAN.md