docs/requirements/
  README.md
  TEMPLATE.md
  req-NNN/
    req-NNN_<slug>.md
    test-catalog.md
    test-evidence.md
    history/
      provenance-reapproval-request.md
      README.md

NNN: requirement ID의 세 자리 decimal number. 폴더명과 정본 파일의 번호는 일치해야 한다.
<slug>: requirement title을 나타내는 lowercase kebab-case ASCII slug
req-NNN/는 하나의 requirement 묶음이며, 그 안의 req-NNN_<slug>.md만 정본이다.
test-catalog.md는 AC와 실행 가능한 테스트의 연결을, test-evidence.md는 특정 commit·환경에서의 실행 결과를 기록한다. 이들은 보조 문서이며 별도 REQ ID, revision 또는 approval status를 부여하지 않는다.
과거 승인 요청·정정 절차 기록은 필요할 때 history/에 보존한다. 당시 요청서와 현재 완료 상태를 구분하고, 완료 상태 및 승인 근거는 history/README.md에 기록한다.
docs/requirements/ 바로 아래에는 공통 README/TEMPLATE와 requirement별 폴더를 둔다. 개별 REQ나 보조 문서를 이 위치에 혼재시키지 않는다.
문서 검색·수집은 하위 폴더까지 탐색하고, 파일 접두사만이 아니라 JSON front matter의 schema와 id로 정본을 식별한다.
배치 변경만으로 승인된 정본의 내용·ID·revision·status를 변경하지 않는다.

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/req-001_manual-cash-dividend.md").read_text(encoding="utf-8")
_, metadata_json, _ = text.split("---", 2)
metadata = json.loads(metadata_json)

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