feat: Enable DSL validation for project specs (#39)

This change makes the project dogfood the DSL validator by:

1. Adding new builtin module types:
   - SpecificationModule: For spec files like markdown-link-validator.md
   - PrinciplesModule: For principles.md

2. Restructuring specs to pass validation:
   - Removed duplicate job catalog files (specs/jobs/*.md)
   - Removed broken job references from spec files
   - Added "Addresses" sections to Requirements linking to Jobs

3. Fixed bugs in DSL validator:
   - Fixed reference_resolver.py using target_module instead of target_type
   - Added "addresses" keyword detection in reference_extractor.py
   - Added metadata location support for identifier extraction
   - Imported MarkdownDocument type in validator.py

4. Added DSL validation to CI workflow

All specs now pass DSL validation with 0 errors. The only remaining
messages are 3 info messages about future/ docs not matching any type,
which is expected.

Validation results:
- Documents validated: 13
- References validated: 6
- Errors: 0
- Warnings: 0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: calvingiles

.github/workflows/ci.yml

@@ -74,3 +74,6 @@ jobs:
 
     - name: Validate spec schema
       run: uv run spec-check check-schema --verbose
+
+    - name: Validate DSL structure
+      run: uv run spec-check validate-dsl --builtin-types specs/

spec_check/dsl/builtin_types.py

@@ -16,7 +16,9 @@
     AcceptanceCriterion,
     ArchitectureDecisionModule,
     JobModule,
+    PrinciplesModule,
     RequirementModule,
+    SpecificationModule,
 )
 
 # ============================================================================
@@ -28,6 +30,8 @@
     "Job": JobModule(),
     "Requirement": RequirementModule(),
     "ADR": ArchitectureDecisionModule(),
+    "Specification": SpecificationModule(),
+    "Principles": PrinciplesModule(),
 }
 
 # Export built-in class types
@@ -41,5 +45,7 @@
     "JobModule",
     "RequirementModule",
     "ArchitectureDecisionModule",
+    "SpecificationModule",
+    "PrinciplesModule",
     "AcceptanceCriterion",
 ]

spec_check/dsl/layers.py

@@ -213,6 +213,77 @@ class ArchitectureDecisionModule(SpecModule):
     ]
 
 
+class PrinciplesModule(SpecModule):
+    """
+    Principles Document.
+
+    Documents architectural principles, design philosophy, and guiding
+    tenets for the project. Typically one per project.
+
+    Example filename: principles.md
+    Location: specs/
+    """
+
+    name: str = "Principles"
+    version: str = "1.0"
+    description: str = "Principles Document"
+
+    # Match principles.md specifically
+    file_pattern: str = r"^principles\.md$"
+    location_pattern: str = r"^specs/[^/]+\.md$"
+
+    # No identifier required for principles
+    identifier: IdentifierSpec | None = None
+
+    sections: list[SectionSpec] = [
+        SectionSpec(heading="Overview", heading_level=2, required=False),
+    ]
+
+    references: list[Reference] = []
+
+
+class SpecificationModule(SpecModule):
+    """
+    Specification Document (SPEC).
+
+    Specifications document detailed requirements for a system or feature.
+    They typically contain multiple requirements organized into sections.
+
+    Example filename: SPEC-001.md (or named like markdown-link-validator.md)
+    Location: specs/
+    """
+
+    name: str = "Specification"
+    version: str = "1.0"
+    description: str = "Specification Document"
+
+    # Match files starting with SPEC- or specific spec names
+    file_pattern: str = r"^(SPEC-\d{3}|markdown-[\w-]+|spec-[\w-]+)\.md$"
+    # Match files directly in specs/ root, excluding subdirs
+    location_pattern: str = r"^specs/[^/]+\.md$"
+
+    identifier: IdentifierSpec = IdentifierSpec(
+        pattern=r"SPEC-\d{3}",
+        location="metadata",  # ID is in metadata section
+        scope="global",
+    )
+
+    sections: list[SectionSpec] = [
+        SectionSpec(heading="Overview", heading_level=2, required=False),
+        SectionSpec(heading="Requirements", heading_level=2, required=False),
+    ]
+
+    references: list[Reference] = [
+        Reference(
+            name="addresses",
+            source_type="Specification",
+            target_type="Job",
+            cardinality=Cardinality(min=0, max=None),
+            link_format="id_reference",
+        ),
+    ]
+
+
 # ============================================================================
 # Registry of Layer-Specific Types
 # ============================================================================
@@ -221,4 +292,6 @@ class ArchitectureDecisionModule(SpecModule):
     "Job": JobModule(),
     "Requirement": RequirementModule(),
     "ADR": ArchitectureDecisionModule(),
+    "Specification": SpecificationModule(),
+    "Principles": PrinciplesModule(),
 }

spec_check/dsl/reference_extractor.py

@@ -263,6 +263,8 @@ def _infer_relationship(
                 return "implements"
             if "dependencies" in section_lower or "prerequisites" in section_lower:
                 return "depends_on"
+            if "addresses" in section_lower:
+                return "addresses"
 
         # Check module definition for context
         if module_def and section:

spec_check/dsl/reference_resolver.py

@@ -143,10 +143,10 @@ def _resolve_module_reference(
         warning = None
         if module_def and reference.relationship:
             ref_def = self._find_reference_definition(module_def, reference.relationship)
-            if ref_def and ref_def.target_module:
-                if target_module.module_type != ref_def.target_module:
+            if ref_def and ref_def.target_type:
+                if target_module.module_type != ref_def.target_type:
                     warning = (
-                        f"Type mismatch: expected {ref_def.target_module}, "
+                        f"Type mismatch: expected {ref_def.target_type}, "
                         f"found {target_module.module_type}"
                     )
 

spec_check/dsl/validator.py

@@ -11,10 +11,11 @@
 - Pass 7: Reference Resolution (reference_resolver.py)
 """
 
+import re
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from spec_check.ast_parser import parse_markdown_file
+from spec_check.ast_parser import MarkdownDocument, parse_markdown_file
 from spec_check.dsl.id_registry import IDRegistry
 from spec_check.dsl.models import SpecModule
 from spec_check.dsl.reference_extractor import (
@@ -145,6 +146,9 @@ class DocumentContext:
     content: str
     """Markdown content."""
 
+    parsed_doc: MarkdownDocument | None = None
+    """Parsed markdown document with metadata."""
+
     module_def: SpecModule | None = None
     """Matched module definition."""
 
@@ -283,6 +287,7 @@ def _process_document(self, file_path: Path) -> None:
             self.documents[file_path] = DocumentContext(
                 file_path=file_path,
                 content=content,
+                parsed_doc=doc,
                 section_tree=section_tree,
             )
 
@@ -366,7 +371,15 @@ def _extract_module_id(self, doc_ctx: DocumentContext, module_def: SpecModule) -
             if root.subsections and root.subsections[0].section_id:
                 return root.subsections[0].section_id
 
-        # TODO: Support frontmatter and other locations
+        elif location == "metadata":
+            # Extract from document metadata (frontmatter or bold key-value pairs)
+            if doc_ctx.parsed_doc and doc_ctx.parsed_doc.metadata:
+                # Look for ID field in metadata
+                for key, value in doc_ctx.parsed_doc.metadata.items():
+                    if key.upper() == "ID" and re.match(module_def.identifier.pattern, value):
+                        return value
+
+        # TODO: Support heading and other locations
 
         return None