---
_version: '1'
uuid: 81e63bac-4035-47b5-b273-ac13e47a2ff6
created: 2025-07-22T13:14:40.510075462Z
parents:
- uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
fingerprint: 0be18be02fc9d9375111dba8b44f475d5acb08a05cce70105d9c62bbd8b92993
hrid: USR-001
---
# SYS-001 Markdown File Format with YAML Frontmatter
## Statement
Each requirement shall be stored as a single plain-text Markdown file containing a YAML frontmatter block and a Markdown body. The HRID (Human-Readable ID) must appear as the first token in the document's first heading.
## Rationale
Plain-text storage enables version control, diff viewing, and collaborative editing using standard software development tools (Git, text editors, IDEs). Markdown provides human-readable formatting that renders well in documentation systems. YAML frontmatter separates structured metadata from content, allowing automated processing while maintaining readability. Storing the HRID in the heading enables integration with documentation generators like Sphinx and MdBook, which extract page titles from headings rather than frontmatter.
## Implementation Notes
- File format: `{HRID}.md` (e.g., USR-001.md, SYS-001.md)
- YAML frontmatter delimited by `---` markers at the start of the file
- HRID appears as the first token in the first markdown heading (e.g., `# USR-001 Title`)
- Body content follows standard Markdown syntax
- Frontmatter contains metadata: version, UUID, created timestamp, tags, parent links
- The HRID is NOT stored in the frontmatter - it is extracted from the title
## File Format Example
```markdown
---
_version: '1'
uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
created: 2025-07-22T12:19:56.950194157Z
parents:
- uuid: parent-uuid-here
fingerprint: parent-fingerprint-hash
hrid: PARENT-001
---
# USR-001 Plain Text Storage
Requirements are stored as plain-text files...
```
## Verification
- Tool successfully parses files with valid YAML frontmatter
- Tool extracts HRID from the first heading in the markdown content
- Tool extracts metadata fields correctly from frontmatter
- Tool renders Markdown body content
- Invalid frontmatter or missing HRID in title produces clear error messages