SEA™ Spec-Guard Integration

This guide covers integrating spec validation into your development workflow and CI/CD pipeline.

1. Overview

Spec-Guard validates all specifications against SEA™ Forge’s governance requirements:

• Syntax validation: YAML frontmatter, markdown structure
• Cross-reference validation: Links between ADR→PRD→SDS
• Completeness checks: Required fields present
• Consistency checks: No conflicting specifications
• Governance validation: SEA™ DSL policy correctness

2. Running Spec-Guard

2.1 Full Validation

1
2
3
4
5
6
7
# Validate all specifications
just spec-guard

# Expected output:
# ✓ 150 specs validated
# ✓ 0 errors
# ⚠ 3 warnings (optional review)

2.2 Single File Validation

1
2
3
4
5
# Validate specific SDS
just sds-validate docs/specs/semantic-core/sds/002-dsl-management.md

# Validate SEA™ DSL
just sea-validate docs/specs/semantic-core/domain.sea

2.3 CI Integration

Spec-Guard runs automatically in CI:

1
2
3
4
5
6
# .github/workflows/ci.yml
jobs:
  validate:
    steps:
      - name: Validate Specs
        run: just spec-guard

3. Validation Rules

3.1 YAML Frontmatter

Every spec must have valid frontmatter:

1
2
3
4
5
6
7
8
9
10
11
---
id: SDS-XXX
title: Service Name
status: draft | approved | deprecated
version: 1.0.0
references:
  - type: adr
    id: ADR-XXX
  - type: prd
    id: PRD-XXX
---

3.2 Cross-References

All references must resolve:

1
2
3
4
5
references:
  - type: adr
    id: ADR-001  # Must exist at docs/specs/shared/adr/001-*.md
  - type: sds
    id: SDS-035  # Must exist at docs/specs/*/sds/035-*.md

3.3 Required Sections

SDS documents must include:

• Overview
• API Specification
• Data Model
• Governance (if applicable)
• Invariants (if applicable)

3.4 SEA™ DSL Validation

1
2
3
4
5
6
7
just sea-validate <file>

# Checks:
# - Syntax correctness
# - Entity references exist
# - Policy structure valid
# - No circular dependencies

4. Error Resolution

4.1 Missing Reference

Error: Reference not found: ADR-042

Solution:

1. Create the missing spec: just /spec adr
2. Or fix the reference to correct ID

4.2 Invalid Frontmatter

Error: Invalid YAML in frontmatter

Solution:

1. Check YAML syntax (indentation, colons, quotes)
2. Validate with: yq . docs/specs/<file>.md

4.3 SEA™ DSL Syntax Error

Error: Unexpected token at line 15

Solution:

1. Review docs/reference/sea_dsl_language_reference.yml
2. Check for missing keywords or wrong structure
3. Validate incrementally

4.4 Missing Required Section

Error: Required section missing: Governance

Solution:

1. Add the missing section to the document
2. Use template for proper structure

5. Pre-Commit Integration

5.1 Git Hooks

1
2
3
# .githooks/pre-commit
#!/bin/bash
just spec-guard || exit 1

5.2 Enable Hooks

1
git config core.hooksPath .githooks

6. Advanced Usage

6.1 Staged Files Only

1
2
# Validate only staged files (faster)
just spec-guard-staged

6.2 With Detailed Output

1
2
# Verbose output
just spec-guard --verbose

6.3 Generate Report

1
2
# Generate validation report
just spec-guard --report > validation-report.json

7. Troubleshooting

Issue: Spec-Guard Times Out

Solution:

1
2
3
4
5
# Run in parallel
just spec-guard --parallel

# Or validate specific context
just spec-guard --dir docs/specs/semantic-core

Issue: False Positives

Solution:

1. Check if warning is valid
2. Add exception if intentional: ```yaml

   In frontmatter

   exceptions:

   • rule: cross-reference-check reason: “Intentionally forward reference” ```