docs: align guidance with simplified agent and harness workflow

docs/FEATURE_DOCUMENTATION.md

@@ -1,79 +1,82 @@
 # Feature 문서 관리
 
-이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면
-`docs/<feature-id>/`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다.
-`<feature-id>`는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다.
+지속할 요구사항·계약·검증 evidence가 필요한 solver Feature에는 `docs/<feature-id>/`를
+사용한다. 메인 assistant가 안정적인 kebab-case Feature ID를 정하고 context와 문서 목록을
+관리한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다.
+현재 운영은 [ADR-028](ADR.md#adr-028)과 [Agent 계약](SOLVER_AGENT_DESIGN.md)을 따른다.
 
 ## 시작과 참조
 
-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으로 참조한다.
+1. 새 Feature 폴더를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다.
+   재개 시 기존 계약과 evidence를 읽고 필요한 부분만 갱신한다.
+2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 일반 Feature
+   작업에서 읽기 전용 기준이다. Feature 진행 링크를 공통 문서에 누적하지 않으며 공통
+   지침 변경은 별도 사용자 요청 범위에서 수행한다.
+3. Specialist는 할당 작업에 관련된 Feature 문서와 원문의 절만 읽는다.
+   `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니므로 필요한 context는
+   메인이 경로·절로 전달한다. 모든 인계에서 핵심 문서 3개를 재독하도록 강제하지 않는다.
+4. 기존 `docs/features/<feature-id>/`와 `coordination.md`는 이력으로 보존한다.
+   자동 이동·복제하지 않고 재개에 필요한 경로·계약 revision을 참조한다.
+   `coordination.md`를 새로 생성하거나 현재 상태 기록을 위해 갱신하지 않는다.
 
-이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의
-기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다.
-Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당
-계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다.
+Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 실제 상위 계약 문제는
+해당 owner와 메인에 evidence를 전달하고 필요한 사용자 결정을 따른다.
 
-## 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와 해당 산출물 |
+| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당된 owner와 유용한 문서 목록. 현재 checklist는 PRD에 연결 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
+| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본, 필요한 상세 계약 링크 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
+| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거. 실제 결정이 없으면 그 사실과 적용 공통 결정 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
 
-- 각 관리 문서는 현재 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 작업만으로 프로젝트 기준 문서를 갱신하지 않는다.
+- 현재 checklist는 PRD 한 곳에서 관리한다. 문서 목록이나 별도 파일에 같은 상태를
+  중복 기록하지 않는다.
+- 작은 요구사항·acceptance는 PRD에 직접 정의한다. 복잡하여 분리할 필요가 있을 때만
+  `requirements.md`나 상세 verification matrix를 작성하고 PRD에는 요약과 링크를 둔다.
+  분리된 전문 계약은 할당된 owner가 소유한다.
+- 메인은 관련 반환을 확인하여 목록·링크·checklist를 갱신한다. Specialist는 할당된
+  문서만 수정하며 downstream이 upstream 계약을 결과에 맞춰 변경하지 않는다.
+- 승인되지 않은 내용이나 아직 실행하지 않은 검증을 승인·완료로 표시하지 않는다.
+  일반 문서 작성·업데이트를 위해 반복적인 승인 gate를 추가하지 않는다.
+- 각 핵심 문서는 실제 프로젝트 기준을 상대 Markdown 링크로 연결한다. 필요한 운영
+  설명은 `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md`를 참조한다.
 
-## Agent 산출물 작성
+## 필요한 상세 문서와 evidence
 
-각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되
-필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다.
+결과를 지지하는 다음 내용만 필요한 만큼 기록한다.
 
-1. 식별: Feature ID, owner, 입력 contract revision.
-2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견.
-3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값.
-4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조.
+1. 해당 Feature·작업·owner와 적용 계약 또는 관련 revision.
+2. 판단·결정, 구현·검토에 필요한 정의와 주요 발견.
+3. 출처·evidence 경로, 실제 명령·exit code·결정적 측정값과 적용 기준.
+4. 가정, 미지원 범위, 미해결 항목·제한과 다음 작업에 필요한 정보.
 
-상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement,
-수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다.
-분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다.
+`research.md`, `formulation.md`, `io.md`, `numerical-review.md`,
+`reference-model.md`, `implementation-report.md`, `build-test.md`,
+`reference-comparison.md`, `physics-evaluation.md`는 필요한 경우의 산출물 예시다.
+간단한 구현·build/test·reference 결과는 하나의 짧은 보고서에 모을 수 있으며 같은 결과를
+여러 기본 보고서에 반복하지 않는다. Release 보고서는 명시적으로 감사를 요청한 경우에만 작성한다.
 
-긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에
-`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를,
-`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다.
+긴 유도·전체 schema·mapping·검증 matrix가 필요하면 같은 폴더의
+`formulation-derivation.md`, `io-schema.md` 같은 문서로 분리하여 관련 본문에서 연결한다.
+상세 문서는 해당 전문 owner가 소유하고 적용되는 계약과 기본 문서를 명확히 연결한다.
+반환할 때 판단에 사용한 상세 evidence 경로도 포함한다. 고정 envelope나 모든 산출물의
+hash·gate 기록은 요구하지 않는다.
 
-- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만
-  적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다.
-- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도
-  기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다.
-- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세
-  문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다.
-- 모든 agent 보고서는 `docs/<feature-id>/`에 저장한다. 소스·테스트·Harness 제어 파일과
-  기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서
-  참조한다.
+짧게 쓰기 위해 필수 수식·identity·units·schema·tolerance·acceptance 정의를 없애지 않는다.
+문서만 수정할 때 원시 로그나 의미 변화 없는 revision 기록을 추가하지 않는다. 실제 계약이
+변경되면 관련 evidence가 여전히 유효한지 확인하며 과거 결과를 현재 검증으로 소급하지 않는다.
+필수 검증을 실행하지 않았다면 미실행 사실과 이유를 남긴다.
 
-## Gate 확인
+소스·테스트·기계 생성 로그/결과·read-only reference artifact는 각자의 지정 경로에 유지하고
+보고서에서 참조한다. 기존 phase 이력은 새 보고서 형식에 맞추어 변경하지 않는다.
+Reference artifact와 tolerance를 구현 결과에 맞추어 수정하지 않는다.
 
-Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다.
-판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다.
-필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의
-검증을 대신하지 않는다.
+## 언어와 확인
+
+기본 Feature 문서는 한국어 Markdown으로 작성하고 agent/skill ID, field, requirement ID,
+경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ-<FEATURE>-###`다.
+
+메인은 실제 파일·소유권·상대 링크와 판단에 필요한 evidence를 확인한다. 필수 상세 근거가
+없거나 연결이 끊겼다면 해당 owner와 해결하고 요약만으로 검증을 대신하지 않는다.
+문서 정리는 정적 검토로 확인하며 solver build나 수치/reference 검증의 통과로 보고하지 않는다.