Feature Request: Configurable requirement ID pattern for multi-segment IDs

[tracymorris-tech]

Problem Statement

Currently, spec-check has a hardcoded requirement ID pattern that only supports single-segment IDs with exactly 3 digits (e.g., REQ-001, SYS-002). This prevents organizations from using multi-segment categorized requirement IDs (e.g., REQ-DATA-001, SYS-API-007) which are useful for organizing requirements by functional area.

Current Behavior

The requirement ID pattern is hardcoded in spec_check/ast_parser.py:174:

REQ_ID_PATTERN = re.compile(r"\*\*([A-Z]+-\d{3})\*\*:")
This pattern:
Only matches single-segment IDs: **REQ-001**:
Requires exactly 3 digits
Does not match multi-segment IDs: **REQ-DATA-001**:, **SYS-API-007**:
Result: When running spec-check check-coverage with multi-segment IDs, the tool reports 0 total requirements found in specs, even though requirements are properly formatted. Example output:
Coverage: 0.0%
Requirements: 5/0 covered
(Found 5 requirement IDs in test markers, but 0 requirements in spec files)
Our Use Case
We organize requirements using a multi-segment categorization scheme: Format: [PREFIX]-[CATEGORY]-[NUMBER] Examples:
REQ-DATA-001: Data model requirements
REQ-METRIC-001: Metric-related features
SYS-API-001: API contract requirements
SYS-PERF-001: Performance requirements
SYS-SEC-002: Security requirements
This categorization:
Organizes requirements by functional area (UI, Admin, API, Performance, Security)
Prevents ID collisions across categories
Improves traceability and searchability
Aligns with industry standards for large specification sets
Proposed Solution
Add a configuration option in pyproject.toml to allow custom requirement ID patterns: Option 1: Full regex override
[tool.spec-check.check-coverage]
specs-dir = "../specs"
tests-dir = "tests"
min-coverage = 80.0
requirement-id-pattern = "\\*\\*([A-Z]+-[A-Z]+-\\d+)\\*\\*:"  # Custom regex
Option 2: Separate ID pattern from formatting (more flexible)
[tool.spec-check.check-coverage]
specs-dir = "../specs"
tests-dir = "tests"
min-coverage = 80.0
requirement-id-style = "bold-text"  # or "markdown-header"
requirement-id-pattern = "([A-Z]+-[A-Z]+-\\d+)"  # Just the ID portion
Additional Enhancement (Optional)
Support for markdown headers as an alternative to bold text:
Current: **REQ-001**: Requirement Title (bold text)
Alternative: ## REQ-001: Requirement Title (markdown header)
Many specification frameworks use headers for requirements rather than bold text. Supporting both would increase spec-check's compatibility with existing documentation standards.
Workaround Currently Using
We are temporarily:
Converting our markdown headers to bold text format
Patching the regex locally to accept multi-segment IDs
This works but requires maintaining a fork and diverging from our specification standards.
Example Spec File
Our current requirement format:
## Product Requirements

**REQ-DATA-001**: Core Entity Hierarchy

The system MUST support a three-level hierarchy: Puna → Outcome → Opportunity.

**Acceptance Criteria:**
- Each Outcome belongs to exactly one Puna
- Each Opportunity belongs to exactly one Outcome
- Deleting a Puna cascades to all child Outcomes and Opportunities

---

**SYS-API-001**: Core Entity CRUD APIs

The backend MUST provide RESTful APIs for creating, reading, updating, and deleting core entities.

**Acceptance Criteria:**
- All endpoints require authentication
- All write operations require authorization checks
- All responses return standardized error codes
Example Test File
Our test markers reference these requirement IDs:
import pytest

@pytest.mark.req("REQ-DATA-001")
@pytest.mark.req("SYS-API-001")
def test_create_outcome_with_parent_puna(db_session):
    """Test that outcomes can be created with parent puna relationship"""
    # Test implementation...
Benefits
Implementing this feature would:
✅ Support diverse requirement ID naming schemes
✅ Improve spec-check adoption for organizations with existing specification standards
✅ Enable better requirement organization for large projects
✅ Maintain backward compatibility (default pattern remains unchanged)
Environment
spec-check version: 0.2.0a1
Python version: 3.12
Installation method: uv add --dev spec-check@git+https://github.com/TradeMe/spec-check.git
Thank you for building spec-check! We're excited to use it for maintaining traceability between our specifications and test suite. This configuration option would make it much more flexible for diverse documentation standards.