docs(requirements): approve manual cash dividend contract

2026-09-09 20:19:39 +09:00
parent 6df3e4ba02
commit 78e347703e
3 changed files with 851 additions and 0 deletions
@@ -0,0 +1,48 @@
+# 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다.