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

2026-07-29 16:48:03 +09:00
parent c39406bbdd
commit 41501b5d06
520 changed files with 95494 additions and 2231 deletions
@@ -1,130 +1,165 @@
 # Architecture

-## 1. 설계 목표
+## 1. 목표

-ClariDoc의 핵심 목표는 생성 모델의 문장 능력보다 **정보 구조, 근거 추적, 검토 독립성, 재현 가능한 품질 판정**을 상위 제어 계층에 두는 것이다.
+ClariDoc은 문장 생성 능력보다 다음 제어 계층을 우선한다.

-설계 원칙:
-
-1. **Contract before prose**: 초안보다 브리프와 문서 유형 계약을 먼저 검증한다.
-2. **Reader-question chain**: 각 절은 하나의 독자 질문에 답한다.
-3. **Deterministic minimums**: 모델이 놓치기 쉬운 형식·안전·인용 조건은 코드로 검사한다.
-4. **Role separation**: 작성자와 리뷰 관점을 분리한다.
-5. **Evidence boundary**: 출처의 사실과 모델의 설명·추천을 구분한다.
-6. **Auditability**: 원문 응답, 정규화 입력, 결과, 이벤트, 해시를 보존한다.
-7. **Safe degradation**: planner가 실패하면 결정적 구조로 폴백하지만 writer 실패는 숨기지 않는다.
+1. 독자 과업과 문서 유형 계약
+2. 프로젝트 근거의 수집과 source hierarchy
+3. 기술 선택의 rationale completeness
+4. 독자용 prose와 내부 provenance의 격리
+5. 결정적 검사와 독립 reviewer
+6. 재현 가능한 artifact와 hash manifest

 ## 2. 구성요소

 ```text
-models.py       입력/출력 계약과 검증
-structures.py   문서 유형별 필수 section intent와 순서
-prompts.py      planner/writer/reviewer/reviser 출력 계약
-providers/      Codex, Claude, Antigravity, Mock 어댑터
-lint.py         모델과 독립적인 Markdown/논리 프록시 검사
-pipeline.py     단계 실행, 수정 루프, 품질 게이트, 감사 산출물
+models.py       brief/source/outline/review/pipeline 계약
+corpus.py       로컬 문서 탐색, heading chunk, ranking, source-pack 생성
+structures.py   문서 유형별 필수 section intent와 decision requirements
+prompts.py      planner/writer/reviewer/reviser 경계와 출력 계약
+providers/      Codex, Claude, Antigravity, Mock adapter
+lint.py         구조, 메타 누출, rationale, 안전성의 결정적 검사
+provenance.py   evidence-map.json과 provenance.md 생성
+pipeline.py     단계 실행, 리뷰, 수정 루프, quality gate, manifest
 report.py       사람이 읽는 품질 보고서
-cli.py          init/validate/outline/lint/run/doctor 명령
+cli.py          init/collect/validate/outline/lint/run/doctor
 ```

-## 3. 단계별 상태 전이
+## 3. 입력 계층

-### 3.1 계약 입력
+### 3.1 Brief

- `Brief`: 독자, 목표, 핵심 메시지, 범위, 비범위, 선행지식, 필수 주제, 버전 맥락, 금지 주장
- `SourcePack`: 출처 식별자와 출처가 실제로 지지하는 사실 단위
- `PipelineConfig`: 각 역할의 provider, timeout, 옵션, 품질 게이트
+Brief는 주제보다 독자 과업과 판단 경계를 먼저 고정한다.

-입력은 정규화되어 `inputs/`에 기록된다.
+- audience / prior knowledge / needs
+- reader goal / core message
+- scope / non-scope
+- prerequisites / required topics
+- citation style / date policy / style profile
+- forbidden claims

-### 3.2 결정적 기본 outline
+### 3.2 SourcePack

-`structures.py`가 `document_type`에 따라 필수 intent를 만든다. 각 section은 다음 계약을 가진다.
+Source는 단순 URL이 아니라 다음 metadata를 가질 수 있다.

 ```json
 {
-  "id": "04-mechanism",
-  "intent": "mechanism",
-  "title": "해결 방식이 동작하는 과정",
-  "reader_question": "구성요소와 데이터 흐름은 어떻게 연결되는가?",
-  "purpose": "메커니즘을 단계적 인과 사슬로 설명한다.",
-  "must_include": ["구성요소", "데이터 또는 제어 흐름", "불변조건"],
-  "evidence_ids": ["S1"],
-  "transition_to_next": "다음 독자 질문으로 연결한다."
+  "id": "L1234abcd",
+  "title": "...",
+  "url": "repo:///raw/branch-notes/example.md",
+  "facts": ["heading chunk text"],
+  "source_type": "branch-note",
+  "status": "verified",
+  "path": "raw/branch-notes/example.md",
+  "heading": "결정 사항",
+  "line_start": 120,
+  "line_end": 150,
+  "claim_ids": ["TX-C1"],
+  "decision_ids": ["D13"],
+  "priority": 21.7
 }
 ```

-### 3.3 Planner 정교화
+이 metadata는 내부 reasoning과 audit에 사용된다. `citation_style=hidden`에서는 독자용 문서로 출력되지 않는다.

-Planner는 section 제목, 질문, 목적, `must_include`, 근거 배치, 전환을 개선한다. `reconcile_outline`은 다음을 거부한다.
+## 4. Local corpus retrieval

- 문서 유형 변경
- 필수 intent 삭제
- intent 중복
- 필수 순서 변경
- 존재하지 않는 source ID
+`corpus.py`는 다음 순서로 동작한다.

-Planner 실행 또는 JSON 파싱이 실패하면 기본 outline을 사용하고 경고를 기록한다.
+1. configured include directory를 순회한다.
+2. Markdown frontmatter에서 title/status를 읽는다.
+3. heading 단위로 chunk를 만든다.
+4. query와 각 chunk를 BM25 계열 점수로 비교한다.
+5. source type, status, decision/rationale 용어에 가중한다.
+6. 파일별 최대 chunk 수와 전체 top-k를 적용한다.
+7. repository-relative provenance를 포함한 SourcePack으로 변환한다.

-### 3.4 Writer
-
-Writer는 exact H1과 exact H2 순서를 지켜 전체 Markdown을 반환해야 한다. 브리프와 출처는 지시가 아닌 untrusted data로 경계 표시된다. Writer 실패는 대체 텍스트로 숨기지 않고 실행 오류로 종료한다.
-
-### 3.5 결정적 린트
-
-린터는 모델 응답과 독립적으로 구조, 형식, 절차, 안전, 근거 표식을 검사한다. 자연어 의미를 완전히 판단하지 않으며 **최소 품질 바닥**을 제공한다.
-
-### 3.6 독립 리뷰
-
-각 reviewer는 동일한 초안을 다른 실패 함수로 검사한다.
-
- logic: 전제→결론, 인과 단절, 모순, section 역할
- reader: 선행지식, 방향 감각, 점진 공개, 예시, scan path
- evidence: 출처 적합성, 지원되지 않은 확신, 버전 민감성
- operations: 절차 순서, 검증, 파괴적 조작, 복구, 관측
- editor: 문장·문단 초점, 용어, 중복
-
-리뷰 응답은 고정 JSON 스키마로 파싱된다. 필수 reviewer가 실패하면 기본적으로 실행이 실패한다. `fail_on_reviewer_error: false`는 실패 리뷰를 blocker/0점으로 기록해 산출물을 남긴다.
-
-### 3.7 품질 게이트와 수정
+Source precedence:

 ```text
-model_mean = mean(review.score)
-composite = lint.score * deterministic_weight + model_mean * model_weight
-PASS = composite >= minimum_score
-       AND blockers <= max_blockers
-       AND errors <= max_errors
+canonical-project
+  > canonical-concept
+  > branch-note
+  > official-doc
+  > company-tech-blog
+  > local-document
 ```

-FAIL이고 수정 한도가 남으면 reviser가 lint와 모든 리뷰를 받아 전체 문서를 다시 작성한다. 수정된 초안은 동일한 린트와 리뷰를 처음부터 통과해야 한다.
+이 순서는 절대적인 진실 순위가 아니다. 현재 프로젝트 상태에는 canonical project가 우선이고, 선택 배경에는 branch note가 더 유용할 수 있다. Planner와 reviewer가 claim 종류에 맞게 사용해야 한다.

-## 4. 신뢰 경계
+## 5. Outline contract

-| 경계 | 신뢰 수준 | 처리 |
-|---|---|---|
-| pipeline config | 로컬 운영자가 승인한 코드 수준 설정 | command 실행 가능하므로 반드시 신뢰된 파일만 사용 |
-| brief/source pack | 비신뢰 데이터 | prompt 내부에서 data로 구획, 지시 무시 명시 |
-| model response | 비신뢰 출력 | JSON 파싱·계약 검증·lint·review 수행 |
-| URL | 메타데이터 | 자동 방문/실행하지 않음 |
-| final document | 검토 후보 | PASS여도 도메인 사실·코드 실행을 별도 검증 |
+각 section은 다음 속성을 가진다.

-## 5. 실패 정책
+```json
+{
+  "id": "04-decision-rationale",
+  "intent": "decision_rationale",
+  "title": "선택의 이유와 지킨 경계",
+  "reader_question": "왜 이 선택을 했고 무엇을 포기했는가?",
+  "purpose": "선택을 이유, 대안, 비용, 가드레일과 함께 설명한다.",
+  "must_include": ["선택", "이유", "대안", "수용한 비용", "가드레일"],
+  "evidence_ids": ["L..."],
+  "decision_requirements": [
+    "context_or_constraint",
+    "choice",
+    "why",
+    "alternative",
+    "accepted_cost",
+    "guardrail"
+  ],
+  "transition_to_next": "코드와 흐름으로 연결한다."
+}
+```

-| 단계 | 기본 실패 처리 | 이유 |
-|---|---|---|
-| planner | 결정적 outline 폴백 + 경고 | 구조의 안전한 기본값이 존재 |
-| writer | 실행 중단 | 내용 없는 대체 초안은 유효하지 않음 |
-| reviewer | 실행 중단 | 독립 검토가 구성 계약의 일부 |
-| reviewer, fail-open 설정 | blocker/0점 리뷰로 기록 | 산출물 보존이 필요한 실험 환경 |
-| reviser | 실행 중단 | 수정 실패를 이전 초안 통과로 위장하지 않음 |
-| quality gate fail | final 산출물은 남기되 exit code 4 | 사람이 결함을 분석할 수 있도록 보존 |
+Planner는 제목·질문·근거 배치를 정교화할 수 있지만 intent의 삭제, 추가, 재배열은 할 수 없다.

-## 6. 재현성과 감사
+## 6. Reader/provenance split

- provider 요청의 stage/provider/model/status/duration을 JSONL로 기록
- 각 모델의 raw response와 parsed JSON을 모두 보존
- 입력을 정규화해 실행 시점 계약을 고정
- 최종 산출물을 포함한 파일별 SHA-256 매니페스트 생성
- Mock provider로 외부 네트워크 없이 파이프라인 배선 재현
+### Reader-facing surface

-모델 자체의 비결정성까지 제거하지는 않는다. 운영에서 모델 ID, CLI/SDK 버전, 실행 날짜를 `version_context`, provider `model`, 별도 배포 메타데이터에 고정해야 한다.
+- `final/document.md`
+- 선택 이유와 기술 설명
+- 공개 citation policy에 따른 citation만 포함
+
+### Internal surface
+
+- `final/provenance.md`
+- `final/evidence-map.json`
+- normalized source pack
+- raw provider responses
+- review JSON과 lint report
+- provider event log
+
+Hidden mode에서 internal source ID, repository path, access date가 `document.md`에 보이면 quality gate error다.
+
+## 7. Review topology
+
+- logic: 전제, 인과, 결론
+- decision: context, why, alternative, cost, guardrail
+- reader: orientation, cognitive load, natural prose
+- evidence: claim/source fit, hierarchy, status
+- operations: prerequisites, safety, verification, rollback
+- editor: 문장 흐름과 표현, 질문-답 연결, 정보 구조가 반복 문장 틀로 노출되는지 검사
+
+Writer와 logic·decision·reader·editor·evidence·operations reviewer를 분리해 self-review 편향을 줄이지만, 여러 모델의 일치는 사실 검증을 대신하지 않는다.
+
+## 8. Quality gate
+
+```text
+composite = deterministic_lint × deterministic_weight
+          + model_review_mean × model_weight
+```
+
+통과 조건은 점수와 함께 blocker/error 개수를 검사한다. revision loop가 최대 횟수에 도달하면 실패 상태와 artifact를 그대로 보존한다.
+
+## 9. Failure behavior
+
+- invalid input contract: 실행 전 실패
+- planner invalid JSON/contract: deterministic base outline으로 안전 폴백
+- writer/provider failure: 숨기지 않고 pipeline failure
+- reviewer failure: config에 따라 failure 또는 blocker review
+- revision no-op: warning 기록
+- output path traversal in reviewer role: slug sanitize
+- final artifact: manifest로 크기와 SHA-256 기록