# Requirements

각 requirement는 `req-NNN/` 폴더에 정본과 관련 검증 자료를 함께 둔다. 정본 requirement 문서만 Markdown body 앞에 JSON front matter를 둔다.

## Directory layout and file naming

```text
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

```json
{
  "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 표준 라이브러리로 읽을 수 있다.

```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다.