# ClariDoc Harness 검증 보고서

> 검증일: 2026-07-23  
> 대상 버전: `claridoc-harness 0.1.0`  
> 환경: Linux x86_64, Python 3.13.5  
> 호환성 계약: Python 3.10 이상

## 1. 판정

소스 패키지, 오프라인 Mock 종단 간 파이프라인, 세 provider 어댑터의 격리 테스트, wheel 빌드·설치형 CLI를 검증했다.

**판정: 배포 가능한 개발자용 초기 버전.**

다만 Codex, Claude, Google Antigravity의 실제 실행 파일·SDK·인증이 이 검증 환경에 없으므로, 세 provider에 대한 **실제 모델 호출은 수행하지 않았다.** live 품질이나 계정별 모델 호환성을 증명하는 보고서가 아니다.

## 2. 자동화 테스트

실행 명령:

```bash
bash scripts/test.sh
```

결과:

```text
Ran 31 tests
OK
```

검증 범위:

- 브리프, source pack, pipeline, outline, review 런타임 계약
- 7개 문서 유형의 필수 intent와 순서
- planner 구조 병합의 삭제·순서·출처 위반 차단
- 리뷰의 9개 고정 평가 차원, severity, 유한 수치 검사
- 빈 reviewer 목록, reviewer role 중복, 비정상 품질 게이트 차단
- 필수 H2 누락·중복·순서 검사
- 일반 source ID와 존재하지 않는 source marker 검사
- 파괴적 명령의 영향 경고·복구점·검증 통제
- reviewer role을 통한 artifact 경로 탈출 방지
- Codex와 Claude의 가짜 실행 파일 기반 stdin/출력/인수 계약
- Antigravity의 가짜 SDK 기반 설정 전달, async 응답, 작업 디렉터리 복구
- Mock 종단 간 실행, 수정 한도, 품질 게이트, 이벤트, manifest
- manifest 파일 크기와 SHA-256 재검산
- CLI `init`과 `validate`

Coverage.py로 측정한 statement coverage는 **82%**였다. 이 수치는 테스트 범위의 보조 지표이며 정확성 증명으로 사용하지 않는다.

## 3. Python·JSON·문서 무결성

```bash
bash scripts/verify.sh
```

검증 내용:

- 모든 `src/`와 `tests/` Python 파일을 Python 3.10 grammar로 파싱
- 저장소 JSON 파일 구문 검사
- 로컬 Markdown 상대 링크 해석
- 예제 브리프와 source pack 런타임 검증
- Mock 종단 간 실행
- Mock 점수가 합성값임을 알리는 경고 존재
- 예제 run manifest의 모든 크기와 SHA-256 재검산

별도로 Draft 2020-12 validator를 사용해 다음 인스턴스를 검증했다.

- 예제 brief → `brief.schema.json`
- 예제 source pack → `source-pack.schema.json`
- Mock pipeline과 multi-agent pipeline → `pipeline.schema.json`
- 생성된 outline → `outline.schema.json`
- 네 개의 raw reviewer 응답 → `review.schema.json`

모두 통과했다. `jsonschema`는 검증 환경에서만 사용했으며 ClariDoc core runtime 의존성에는 포함하지 않았다.

## 4. 오프라인 종단 간 실행

실행 명령:

```bash
bash scripts/run-demo.sh
```

결과:

```text
GATE: PASS
SCORE: 89.3/100
```

결정적 lint 점수는 `87.5/100`, blocker와 error는 각각 `0`이었다. 네 reviewer 점수는 모두 Mock fixture가 생성한 합성값이다. `run.json`과 품질 보고서에는 다음 경고가 자동 기록된다.

```text
All providers are deterministic mocks. This run validates pipeline mechanics only;
model-review scores are synthetic and must not be used as evidence of document quality.
```

따라서 이 PASS는 구조 계약, 린터, 리뷰 파싱, 게이트, artifact 배선이 동작했다는 의미다. 외부 모델의 문서 품질이나 예제 문서의 사실성을 의미하지 않는다.

## 5. Wheel 빌드와 깨끗한 설치

빌드 artifact:

```text
dist/claridoc_harness-0.1.0-py3-none-any.whl
SHA-256: 1dd71f73466a255e4a2a22d60482b6c1bc0e629de9d5b17110bcf4f0fb0b4cc6
```

검증 절차:

1. PEP 517 wheel 빌드
2. 새 가상환경 생성
3. wheel을 `--no-deps`로 설치
4. `claridoc --version`
5. `claridoc validate`
6. Mock provider `doctor`
7. 설치된 CLI로 전체 Mock pipeline 실행

결과:

```text
claridoc 0.1.0
VALID: API 재시도는 횟수가 아니라 부하 예산으로 설계한다 (technical_blog), 3 sources
GATE: PASS
SCORE: 89.3/100
```

## 6. Provider 검증 수준

| Provider | 구현 표면 | 수행한 검증 | 실제 호출 |
|---|---|---|---|
| Codex | `codex exec`, stdin, `--output-last-message`, read-only sandbox | 가짜 executable로 command와 출력 수집 검증 | 미수행 |
| Claude | `claude -p --output-format text`, stdin | 가짜 executable로 piped prompt와 stdout 검증 | 미수행 |
| Antigravity | `google.antigravity.Agent`, `LocalAgentConfig`, async `chat` | 가짜 SDK로 config/model, cwd 격리, async text 검증 | 미수행 |

실제 multi-agent config에 대한 `doctor` 결과는 exit code `3`이며 세 항목 모두 `MISSING`이었다.

```text
[MISSING] codex: codex exec
[MISSING] claude: claude -p
[MISSING] antigravity: google-antigravity SDK
```

`doctor`는 설치 여부만 진단한다. 설치 후에도 로그인, 조직 권한, quota, 모델 ID, SDK 버전별 옵션은 live invocation으로 확인해야 한다.

## 7. 확인된 제한

- source pack의 URL을 자동 방문하거나 사실을 자동 수집하지 않는다.
- source marker가 존재해도 문장이 source fact를 정확히 함의하는지는 완전하게 증명하지 않는다.
- LLM reviewer 간 합의는 진실의 증명이 아니다.
- 코드 예제와 명령을 실제 대상 시스템에서 실행하지 않는다.
- 한국어·영어 문장 길이와 문단 분리는 휴리스틱이다.
- Windows용 `run-demo.ps1`은 제공하지만 이 Linux 환경에는 PowerShell이 없어 실행 검증하지 않았다.
- 실제 게시 전에는 도메인 소유자 검토, 코드 실행, 보안 검토, 출처 원문 대조가 필요하다.

## 8. 재현 명령

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

bash scripts/verify.sh
claridoc doctor --config config/pipeline.multi-agent.example.json
```