modify documents

docs/FEATURE_DOCUMENTATION.md

@@ -0,0 +1,79 @@
+# Feature 문서 관리
+
+이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면
+`docs/<feature-id>/`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다.
+`<feature-id>`는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다.
+
+## 시작과 참조
+
+1. 새 요구사항이면 Feature 폴더를 만들고 아래 관리 문서 4개를 작성한다. 같은 Feature를
+   재개하면 기존 문서와 상태를 읽고 필요한 부분만 갱신한다.
+2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 읽기 전용
+   기준으로 참조한다. Feature 진행을 위해 본문이나 현재 작업 링크를 추가·수정하지 않는다.
+3. 각 agent는 dispatch의 Feature 폴더에서 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 읽고
+   자신에게 필요한 계약과 상세 문서만 따라간다. `FEATURED_AGENTS.md`는 자동으로 로드되는
+   `AGENTS.md`가 아니므로 Coordinator가 모든 dispatch와 Harness step의 필수 입력에 명시한다.
+4. 기존 `docs/features/<feature-id>/` 자료는 이력이므로 자동 이동하거나 복제하지 않는다.
+   재개에 필요한 기존 자료는 새 폴더의 문서 목록에서 경로와 revision으로 참조한다.
+
+이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의
+기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다.
+Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당
+계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다.
+
+## Coordinator 관리 문서
+
+| 문서 | 필요한 내용 | 참조 기준 |
+| --- | --- | --- |
+| `FEATURED_AGENTS.md` | Feature ID·목적, 이 작업에만 적용되는 지침, agent별 소유 산출물, 문서 목록과 현재 상태 문서 링크 | `../../AGENTS.md`, `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md` |
+| `PRD.md` | 사용자 요구 요약, 범위·제외, acceptance 요약, 검토 상태와 requirement ID별 계약 링크 | `../PRD.md`, `requirements.md`가 작성되면 해당 문서 |
+| `ADR.md` | Feature 결정 ID, 상태, 결정·이유·영향, 결정 owner와 승인 근거 링크 | `../ADR.md`, 관련 specialist 계약 |
+| `coordination.md` | 현재 stage·outcome·next owner·contract revision, gate 증거, retry 이력, blocker와 다음 작업 | 공통 handoff envelope와 해당 산출물 |
+
+- 각 관리 문서는 현재 Feature ID와 실제 프로젝트 기준 문서에 대한 상대 Markdown 링크를
+  가진다. `FEATURED_AGENTS.md`의 목록은 산출물 경로, owner, revision·검토 상태를 기록한다.
+  현재 stage 등 workflow 상태의 원본은 `coordination.md`이고 목록에서는 이를 참조한다.
+- 최초 `PRD.md`에는 실제 받은 요구사항과 아직 검토되지 않은 상태를 적는다. `ADR.md`에
+  결정이 없으면 그 사실과 적용할 공통 ADR 참조를 적는다. 승인되지 않은 내용을 승인으로
+  표시하거나 이후 stage의 빈 보고서를 미리 만들지 않는다.
+- `requirements.md`의 검증 가능한 요구사항과 matrix는 Requirement Agent가 소유한다.
+  Coordinator는 `PRD.md`에 요약과 링크를 반영하며 별도 요구사항 원본을 만들지 않는다.
+- Coordinator는 각 owner의 반환을 확인한 뒤 목록·상태·`PRD.md`·`ADR.md`의 필요한 참조를
+  갱신한다. 전문 판단을 대신하거나 specialist 본문을 수정하지 않는다.
+- Feature별 결정은 이 폴더의 `ADR.md`에 기록한다. 프로젝트 전반의 기준 변경은 별도 사용자
+  요청 범위에서 다루며, Feature 작업만으로 프로젝트 기준 문서를 갱신하지 않는다.
+
+## Agent 산출물 작성
+
+각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되
+필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다.
+
+1. 식별: Feature ID, owner, 입력 contract revision.
+2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견.
+3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값.
+4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조.
+
+상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement,
+수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다.
+분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다.
+
+긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에
+`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를,
+`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다.
+
+- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만
+  적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다.
+- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도
+  기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다.
+- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세
+  문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다.
+- 모든 agent 보고서는 `docs/<feature-id>/`에 저장한다. 소스·테스트·Harness 제어 파일과
+  기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서
+  참조한다.
+
+## Gate 확인
+
+Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다.
+판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다.
+필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의
+검증을 대신하지 않는다.