# Requirements

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

## File naming

```text
req-NNN_<slug>.md
```

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

## 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_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다.