# Architecture

## 1. 목표

ClariDoc은 문장 생성 능력보다 다음 제어 계층을 우선한다.

1. 독자 과업과 문서 유형 계약
2. 프로젝트 근거의 수집과 source hierarchy
3. 기술 선택의 rationale completeness
4. 독자용 prose와 내부 provenance의 격리
5. 결정적 검사와 독립 reviewer
6. 재현 가능한 artifact와 hash manifest

## 2. 구성요소

```text
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/collect/validate/outline/lint/run/doctor
```

## 3. 입력 계층

### 3.1 Brief

Brief는 주제보다 독자 과업과 판단 경계를 먼저 고정한다.

- audience / prior knowledge / needs
- reader goal / core message
- scope / non-scope
- prerequisites / required topics
- citation style / date policy / style profile
- forbidden claims

### 3.2 SourcePack

Source는 단순 URL이 아니라 다음 metadata를 가질 수 있다.

```json
{
  "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
}
```

이 metadata는 내부 reasoning과 audit에 사용된다. `citation_style=hidden`에서는 독자용 문서로 출력되지 않는다.

## 4. Local corpus retrieval

`corpus.py`는 다음 순서로 동작한다.

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으로 변환한다.

Source precedence:

```text
canonical-project
  > canonical-concept
  > branch-note
  > official-doc
  > company-tech-blog
  > local-document
```

이 순서는 절대적인 진실 순위가 아니다. 현재 프로젝트 상태에는 canonical project가 우선이고, 선택 배경에는 branch note가 더 유용할 수 있다. Planner와 reviewer가 claim 종류에 맞게 사용해야 한다.

## 5. Outline contract

각 section은 다음 속성을 가진다.

```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는 제목·질문·근거 배치를 정교화할 수 있지만 intent의 삭제, 추가, 재배열은 할 수 없다.

## 6. Reader/provenance split

### Reader-facing surface

- `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 기록