---
_version: '1'
uuid: ccdbddbe-d5d2-4656-b4fe-85e61c02cf63
created: 2025-07-22T13:15:27.996136510Z
parents:
- uuid: 3fc6800c-5acc-457e-baf9-a29b42b663fd
fingerprint: c1e3b80b925d87835c6ac4657c71d052eaff573ed82ba1aca55738183f908175
hrid: USR-002
---
# SYS-002 UUID and HRID Fields
## Statement
Each requirement file shall define a globally unique `uuid` field in the YAML frontmatter. The human-readable identifier (HRID) shall be stored as the first token in the document's first markdown heading.
## Rationale
UUIDs provide immutable, globally unique identifiers for internal operations and link stability. HRIDs provide human-friendly identifiers for navigation and reference. Storing HRIDs in the markdown title (rather than frontmatter) enables better integration with documentation tools like Sphinx and MdBook, which extract page titles from headings.
## Implementation Notes
- UUID: RFC 4122 Version 4 (random UUID), generated automatically and stored in frontmatter
- HRID format: `{KIND}-{NUMBER}` where:
- KIND: Requirement type (USR, SYS, etc.) - uppercase
- NUMBER: Sequential integer, zero-padded (e.g., 001, 002)
- Optional namespace prefix: `{NAMESPACE}-{KIND}-{NUMBER}`
- UUID is the canonical identifier for all internal operations
- HRID is extracted from the first heading in the markdown content (e.g., `# USR-001 Title`)
- HRID is NOT stored in the YAML frontmatter
- Filename typically matches HRID for easy identification (e.g., USR-001.md)
## Verification
- Every requirement file has a unique UUID in the frontmatter that never changes
- HRID appears as the first token in the first markdown heading (e.g., `# USR-001 Title`)
- HRID is not present in the YAML frontmatter
- Tool extracts HRID from heading and validates format on load
- Tool rejects duplicate UUIDs
- Tool rejects invalid HRID formats