portfolio-hub/docs/requirements/README.md

Requirements

각 requirement 문서는 Markdown body 앞에 JSON front matter를 둔다.

File naming

req-NNN_<slug>.md

• NNN: requirement ID의 세 자리 decimal number
• <slug>: requirement title을 나타내는 lowercase kebab-case ASCII slug

Metadata schema

{
  "schema": "proofline.requirement/v1",
  "id": "REQ-NNN",
  "title": "사람이 읽는 제목",
  "revision": "major.minor",
  "status": "draft | approved | retired",
  "depends_on": ["REQ-NNN"],
  "applies_to": ["algorithm-name"],
  "language": "ko"
}

• id: repository 안에서 고유한 requirement identifier
• revision: 사람이 읽는 requirement revision. draft 상태에서 본문을 수정해도 올리지 않으며, approved 상태로 전환할 때 또는 승인된 requirement의 의미를 변경하기 위해 재승인할 때만 올린다.
• status: requirement lifecycle 상태. approved는 명시적인 사용자 승인을 의미한다.
• depends_on: 선행 requirement identifier 목록
• applies_to: requirement가 적용되는 algorithm 또는 product 영역

Python parsing

front matter body는 JSON이므로 별도 dependency 없이 Python 표준 라이브러리로 읽을 수 있다.

import json
from pathlib import Path

text = Path("docs/requirements/req-001_algorithm-input-contract.md").read_text(encoding="utf-8")
_, metadata_json, _ = text.split("---", 2)
metadata = json.loads(metadata_json)

JSON front matter의 revision과 status가 문서의 단일 source of truth다.