docs(requirements): group REQ-001 documents by requirement

docs/requirements/README.md

@@ -1,15 +1,30 @@
 # Requirements
 
-각 requirement 문서는 Markdown body 앞에 JSON front matter를 둔다.
+각 requirement는 `req-NNN/` 폴더에 정본과 관련 검증 자료를 함께 둔다. 정본 requirement 문서만 Markdown body 앞에 JSON front matter를 둔다.
 
-## File naming
+## Directory layout and file naming
 
 ```text
-req-NNN_<slug>.md
+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
+- `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
 
@@ -40,7 +55,7 @@ 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")
+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)
 ```