From dfcafade945613132a8d83d92ffb43c3def52d38 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Thu, 10 Sep 2026 11:22:43 +0900 Subject: [PATCH] docs(requirements): group REQ-001 documents by requirement --- docs/requirements/README.md | 25 +++++++++++++++---- docs/requirements/req-001/history/README.md | 11 ++++++++ .../history/provenance-reapproval-request.md} | 0 .../req-001_manual-cash-dividend.md | 0 .../test-catalog.md} | 0 .../test-evidence.md} | 0 6 files changed, 31 insertions(+), 5 deletions(-) create mode 100644 docs/requirements/req-001/history/README.md rename docs/requirements/{req-001_provenance-reapproval-request.md => req-001/history/provenance-reapproval-request.md} (100%) rename docs/requirements/{ => req-001}/req-001_manual-cash-dividend.md (100%) rename docs/requirements/{req-001_test-catalog.md => req-001/test-catalog.md} (100%) rename docs/requirements/{req-001_test-evidence.md => req-001/test-evidence.md} (100%) diff --git a/docs/requirements/README.md b/docs/requirements/README.md index 505539c..449c3f4 100644 --- a/docs/requirements/README.md +++ b/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_.md +docs/requirements/ + README.md + TEMPLATE.md + req-NNN/ + req-NNN_.md + test-catalog.md + test-evidence.md + history/ + provenance-reapproval-request.md + README.md ``` -- `NNN`: requirement ID의 세 자리 decimal number +- `NNN`: requirement ID의 세 자리 decimal number. 폴더명과 정본 파일의 번호는 일치해야 한다. - ``: requirement title을 나타내는 lowercase kebab-case ASCII slug +- `req-NNN/`는 하나의 requirement 묶음이며, 그 안의 `req-NNN_.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) ``` diff --git a/docs/requirements/req-001/history/README.md b/docs/requirements/req-001/history/README.md new file mode 100644 index 0000000..9e3464f --- /dev/null +++ b/docs/requirements/req-001/history/README.md @@ -0,0 +1,11 @@ +# REQ-001 Approval History + +`provenance-reapproval-request.md`는 승인 기록 정정을 요청했던 당시 문서이며, 현재 승인 대기 요청이 아니다. 역사적 기록 보존을 위해 당시 본문·경로·digest 표기를 수정하지 않았다. + +- 현재 정본: [REQ-001 — 사용자 입력 현금 배당 원장 기록](../req-001_manual-cash-dividend.md) +- 정정 범위: 승인 기록에서 혼동한 OQ 선택지 문구만 정정. 요구사항 계약 변경 없음. +- 최종 재승인: 사용자가 변경된 exact diff와 digest를 최종 재승인함. +- 승인 근거: https://github.com/fourblocks2020/portfolio-hub/pull/33#issuecomment-5602775793 +- 최종 재승인된 정본 SHA-256: `1319d8f008f81d125610d49591dde8ee43d3294e0fdb01a5e69fb01306009b47` + +이번 폴더 재배치는 정본 내용·ID·revision·status를 변경하지 않는다. 요청서 안의 기존 경로는 당시 위치이며, 현재 위치는 위 정본 링크를 따른다. diff --git a/docs/requirements/req-001_provenance-reapproval-request.md b/docs/requirements/req-001/history/provenance-reapproval-request.md similarity index 100% rename from docs/requirements/req-001_provenance-reapproval-request.md rename to docs/requirements/req-001/history/provenance-reapproval-request.md diff --git a/docs/requirements/req-001_manual-cash-dividend.md b/docs/requirements/req-001/req-001_manual-cash-dividend.md similarity index 100% rename from docs/requirements/req-001_manual-cash-dividend.md rename to docs/requirements/req-001/req-001_manual-cash-dividend.md diff --git a/docs/requirements/req-001_test-catalog.md b/docs/requirements/req-001/test-catalog.md similarity index 100% rename from docs/requirements/req-001_test-catalog.md rename to docs/requirements/req-001/test-catalog.md diff --git a/docs/requirements/req-001_test-evidence.md b/docs/requirements/req-001/test-evidence.md similarity index 100% rename from docs/requirements/req-001_test-evidence.md rename to docs/requirements/req-001/test-evidence.md