chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가

docs/EXTENDING.md

@@ -1,66 +1,63 @@
 # Extending ClariDoc
 
-## 새로운 문서 유형
+## 새 문서 유형 추가
 
-1. `DocumentType` enum에 값을 추가한다.
-2. `STRUCTURE_SPECS`에 독자 질문 순서와 section intent를 정의한다.
-3. 각 section에 title, reader question, purpose, must-include를 한국어/영어로 제공한다.
-4. `lint.py`에 해당 유형의 최소 계약을 추가한다.
-5. 모든 intent가 고유하고 최소 section 수를 만족하는 테스트를 추가한다.
-6. Mock writer에 새 intent의 fixture body를 추가하거나 명시적 fallback을 검증한다.
+1. `DocumentType`에 enum 추가
+2. `STRUCTURE_SPECS`에 reader-question 순서 정의
+3. procedural/example/trade-off lint 범주 검토
+4. JSON Schema enum 업데이트
+5. 각 intent가 unique하고 최소 section 수를 만족하는 테스트 추가
 
-새 유형을 만들기 전에 기존 유형의 하위 section으로 충분한지 확인한다. 유형이 늘수록 분류 실패 비용도 커진다.
+## 새 source type 추가
 
-## 새로운 lint rule
+1. `corpus._classify_source`에 path rule 추가
+2. `_SOURCE_WEIGHTS`에 기본 weight 추가
+3. prompt의 source hierarchy에 claim role 정의
+4. canonical/current state와 rationale/history 충돌 규칙 작성
+5. ranking과 provenance 테스트 추가
 
-좋은 결정적 rule은 다음 조건을 만족한다.
+## 새 reviewer 추가
 
-- 모델 없이 같은 입력에 같은 결과
-- 결함 위치와 수정 방향을 설명
-- false positive가 관리 가능
-- blocker/error/warning/info의 위험 수준이 명확
-- 자연어 의미 전체를 안다고 가장하지 않음
+Pipeline config의 reviewer role은 자유 문자열이지만 중복될 수 없다. role-specific prompt가 필요하면 `ROLE_GUIDANCE`에 추가한다.
 
-`LintIssue`의 code prefix를 기존 범주에 맞춘다.
+추천 role:
 
-- `MD`: Markdown 무결성
-- `STR`: 구조
-- `AUD`: 독자/오프닝
-- `READ`: 가독성 proxy
-- `TYPE`: 문서 유형 계약
-- `EVD`: 근거
-- `SAFE`: 안전
-- `VER`: 버전
-- `LEN`: 길이
-- `FIN`: 미완료 표시
+- `editor`: 문장과 heading
+- `security`: threat model과 secret exposure
+- `api`: contract compatibility
+- `domain-owner`: project-specific correctness
 
-## 새로운 reviewer role
+Model review response는 모든 `REVIEW_DIMENSIONS`를 포함해야 한다.
 
-1. `prompts.py`의 `ROLE_GUIDANCE`에 실패 함수를 정의한다.
-2. pipeline config reviewers에 role/provider를 추가한다.
-3. 공통 9개 dimension을 유지하거나 조직용 dimension을 parser와 보고서에 명시적으로 확장한다.
-4. 다른 reviewer와 중복되는 일반 교정이 아니라 독립적인 결함 탐지 관점을 제공한다.
+## 새 provider 추가
 
-예: accessibility, localization, API consistency, security threat modeling.
+`Provider` interface를 구현한다.
 
-## 출처 자동 수집기
+```python
+class MyProvider(Provider):
+    def generate(self, request: ProviderRequest) -> ProviderResponse:
+        ...
 
-Core pipeline은 URL을 자동 방문하지 않는다. 수집기를 추가할 때는 별도 단계로 분리한다.
-
-```text
-retriever → immutable evidence snapshot → fact extractor → human/source-owner approval → SourcePack
+    def check(self) -> dict[str, object]:
+        ...
 ```
 
-최종 source pack에는 원문 snapshot hash, 추출 위치, 접근 날짜, 허용된 fact를 남기는 것이 바람직하다. 검색 결과 요약을 바로 source truth로 쓰지 않는다.
+요구사항:
 
-## 실행 가능한 코드 검증
+- prompt는 stdin 또는 안전한 API body로 전달
+- timeout 강제
+- command/error를 audit event로 남길 수 있음
+- cwd 복원과 output isolation
+- credential을 response/event에 기록하지 않음
+- fake executable 또는 fake SDK unit test
 
-코드 블록을 테스트하려면 document generation과 별도의 verifier를 둔다.
+## Rationale lint 확장
 
-1. 언어 태그와 fixture를 추출한다.
-2. 격리된 container/sandbox에서 실행한다.
-3. expected output과 비교한다.
-4. 결과와 로그를 evidence artifact로 저장한다.
-5. 문서의 예시 section과 artifact hash를 연결한다.
+현재 `RAT001`과 `RAT002`는 lexical heuristic이다. 특정 조직의 decision record가 structured field를 갖고 있다면 다음 확장이 가능하다.
 
-문서 모델에게 “코드가 맞다”고 평가하게 하는 것만으로 실행 검증을 대체하지 않는다.
+- decision ID별 required claim type
+- alternative/accepted-cost/guardrail field validation
+- source heading과 claim ID 기반 completeness score
+- canonical implementation state와 branch rationale join
+
+Score를 높이기 위해 heuristic을 약화하지 않는다. false positive를 줄일 때는 regression fixture와 golden example을 함께 추가한다.