donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
109983461765ef5721c3c210019f4658e61f5c24
document-haness/verification/TEST_REPORT.md
T

11 KiB
Raw Blame History

ClariDoc Harness 0.2.0 검증 보고서

  • 검증 대상: claridoc-harness 0.2.0
  • 검증 환경: Linux, Python 3.12.3 runtime
  • 하위 문법 호환 검사: Python 3.10 AST grammar
  • 검증 명령: 변경 중인 working tree 산출물을 덮어쓰지 않도록 격리된 working-copy에서 bash scripts/verify.sh

1. 이번 수정에서 검증하려는 실패

0.2.0은 단순한 기능 추가가 아니라 다음 회귀를 차단하는 수정이다.

  1. 독자용 글에 source ID, 저장소 경로, 접근일, prompt 문장이 나타나는 문제
  2. “의도적으로 사용한다”는 선택 선언 뒤에 이유·대안·비용이 없는 문제
  3. 프로젝트의 branch-note와 canonical 문서를 검색하지 않고 일반론으로 이유를 채우는 문제
  4. 근거에서 이유를 확인하지 못한 SLF4J 선택을 그럴듯하게 설명하는 문제
  5. 독자용 문서와 내부 provenance가 같은 파일에 섞이는 문제
  6. 문제 → 제약 → 대안 → 선택 이유라는 정보 구조가 첫 번째 제약은 같은 반복 문장 틀로 노출되는 문제

검증 스크립트는 이 실패를 unit test와 별도의 artifact-level 회귀 검사로 모두 확인한다.

2. 전체 결과

검증 항목 결과
단위·통합 테스트 44/44 PASS
Statement coverage 미수집 — coverage package 없음
Python 3.10 grammar parse 31개 파일 PASS
JSON 구문 검사 35개 파일 PASS
Draft 2020-12 schema 자체 검사 5개 schema PASS
대표 JSON instance schema 검증 5개 instance PASS
Markdown local link 187개 PASS
Local corpus 검색 10개 evidence chunk 회수
Decision-rationale ranking D13 이유 chunk 1위
Golden example lint 100.0/100, blocker 0, error 0
Golden reader-facing leakage 검사 PASS
Unsupported SLF4J rationale 검사 PASS
Mock 종단 간 pipeline PASS, 95.6/100
Reader/provenance artifact 분리 PASS
Manifest size·SHA-256 재검산 PASS
Wheel 빌드 PASS
새 virtualenv wheel 설치 PASS
설치된 CLI validate/collect/lint/run PASS
실제 Codex·Claude·Antigravity 호출 미수행 — Codex·Claude CLI 확인, Antigravity SDK 없음

3. 테스트와 coverage

실행:

PYTHONPATH=src python3 -m unittest discover -s tests -v

결과:

Ran 44 tests
OK
coverage package unavailable; coverage report skipped

주요 신규 회귀 테스트:

  • local corpus에서 Spring DI 선택 이유가 있는 D13 chunk가 우선 검색되는지
  • repository-relative path와 line range가 보존되는지
  • canonical current-state와 branch decision-history가 함께 회수되는지
  • 독자용 글의 source marker와 meta narration을 error로 잡는지
  • access-date boilerplate를 잡는지
  • 선택 선언 뒤 이유가 없으면 RAT001로 실패하는지
  • golden application-core 예시가 blocker/error 없이 통과하는지
  • heading만 있고 본문이 없는 chunk를 evidence로 수집하지 않는지
  • final artifact에 provenance.md와 evidence-map.json이 생성되는지
  • 한국어 기술 블로그에서 추상 분류명을 세 개의 서수 문단 머리로 반복하면 STYLE001이 발생하는지
  • 실제 절차를 나타내는 번호 목록은 STYLE001로 오인하지 않는지
  • writer·editor·reviser prompt가 정보 구조와 문장 형식을 구분하고 실제 순서 표현은 보존하는지

이번 환경에는 coverage package가 없어 statement coverage를 다시 계산하지 않았다. Coverage 수치가 있더라도 사실 정확성이나 provider 품질을 증명하지는 않는다.

4. Local corpus와 결정 근거 회수

fixture corpus는 실제 저장소 구조를 축소해 다음 경로를 포함한다.

wiki/projects/ca-tmpl
raw/branch-notes
raw/official-docs
raw/company-tech-blogs

검색 질의:

application-core Spring DI 선택 이유 대안 비용 가드레일
TransactionPort spring-tx 금지 ArchUnit 검증

회수 결과는 10개 heading chunk였으며, 1위는 다음 내용을 포함한 branch-note의 결정 사항이었다.

D13: @Service/@Component를 DI 등록 목적으로 허용
이유: DI까지 제거하면 use case bean 수동 @Configuration 등록이 증가
수용 비용: spring-context/spring-beans 의존
경계: spring-tx, Spring Web, JPA 금지

동시에 canonical project 문서에서 Gradle/ArchUnit 검사와 reflection-style bypass 한계를 회수했다. 수집 JSON에는 절대 경로가 없고 repository-relative path와 line range만 남았다.

Negative evidence fixture에는 “이 문서는 application-core가 SLF4J를 사용하는 이유를 설명하지 않는다”는 경계를 넣었다. golden reader-facing example에서 SLF4J가 발견되면 검증이 실패하도록 했다.

5. Golden reader-facing example

대상:

examples/golden/application-core-spring-di-boundary.md

Lint 결과:

score: 100.0
word_count: 993
issues: 0
H1: 1
H2: 8
citation_style: hidden
has_verification: true
has_tradeoffs: true
formulaic_ordinal_opening_count: 0

별도 leakage 검사에서 다음 패턴이 없어야 통과한다.

[S1] 또는 [L...] 내부 marker
근거 팩 / 확인 대상으로 제시
예시는 YYYY-MM-DD 기준
raw/branch-notes/ 또는 wiki/projects/ 경로
repo:/// URL
/home/... 절대 경로

Golden 글에는 Spring DI 허용 이유, 엄격한 무-Spring 대안, 광범위한 Spring 허용 대안, 수용 비용, TransactionPort, Gradle/ArchUnit 가드레일, 정적 분석의 한계가 포함된다. 명시적 이유를 확보하지 못한 SLF4J는 제외했다.

6. Mock 종단 간 pipeline

실행:

bash scripts/run-demo.sh

결과:

GATE: PASS
SCORE: 95.6/100

세부 결과:

deterministic lint: 95.0
logic review: 96.0
decision review: 96.0
reader review: 96.0
editor review: 96.0
evidence review: 96.0
operations review: 96.0
blockers: 0
errors: 0

이 점수는 deterministic mock fixture의 합성값이다. run.json에 다음 경고가 자동 기록된다.

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.

따라서 95.6점은 planner/writer와 logic·decision·reader·editor·evidence·operations reviewer, reviser 배선, 계약 파싱, lint, gate, artifact 생성이 동작했다는 의미다. 실제 모델의 문장 품질을 뜻하지 않는다.

7. Reader-facing 문서와 provenance 분리

Mock pipeline은 다음을 별도 생성했다.

final/document.md
final/quality-report.md
final/provenance.md
final/evidence-map.json

검사 결과:

  • document.md에는 내부 source marker, repository path, access-date boilerplate가 없음
  • provenance.md와 evidence-map.json에는 source ID와 감사 정보가 보존됨
  • run.json이 네 artifact의 역할을 각각 기록함
  • manifest.json이 네 artifact를 모두 포함함
  • manifest의 byte size와 SHA-256을 실제 파일에서 다시 계산해 일치함

8. 정적·schema·링크 검사

31 Python files: Python 3.10 grammar parse PASS
35 JSON files: parse PASS
5 schemas: Draft 2020-12 check_schema PASS
5 representative instances: validation PASS
187 relative Markdown links: target exists

대표 schema instance:

  • retry-policy brief
  • application-core brief
  • manual retry source pack
  • local corpus source pack
  • generated application-core outline

9. Wheel 빌드와 깨끗한 설치

격리된 검증 복사본의 산출물:

dist/claridoc_harness-0.2.0-py3-none-any.whl
size: 76325 bytes
SHA-256: 5f873d5261273e2b0165d4ad0e6e938b4ee98fe1aaa09cb60e13d7f61bf535e6

검증 절차:

  1. PEP 517 wheel 빌드
  2. 임시 virtualenv 생성
  3. wheel을 --force-reinstall --no-deps로 설치
  4. 설치된 claridoc --version 실행
  5. 설치된 CLI로 local-corpus validate
  6. 설치된 CLI로 collect
  7. 설치된 CLI로 golden lint
  8. 설치된 CLI로 Mock pipeline run

결과:

claridoc 0.2.0
validate: PASS, 10 sources
collect: PASS, 8 evidence chunks
lint: PASS
mock run: PASS, 95.6/100

10. Provider 검증 수준

Provider 구현 표면 자동 테스트 현재 live 호출
Codex codex exec, stdin, --output-last-message, read-only sandbox fake executable로 command와 결과 수집 검증 미수행
Claude claude -p --output-format text, stdin fake executable로 piped prompt와 stdout 검증 미수행
Antigravity SDK Agent, LocalAgentConfig, async chat fake SDK로 model/config/cwd/async 응답 검증 미수행

doctor 결과:

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

따라서 이번 보고서는 실제 provider 생성 품질을 검증했다고 주장하지 않는다. binary/SDK 설치 후에도 인증, 조직 권한, quota, model ID와 옵션 호환성은 live invocation으로 확인해야 한다.

11. 실제 private repository 접근 범위

이 검증 컨테이너에는 사용자가 지정한 다음 로컬 경로가 마운트되어 있지 않았다.

/home/donghyeon/workspace/ai-tool/llm-wiki-private

대신 연결된 private GitHub repository에서 다음 문서를 선택적으로 확인해 설계 결함을 진단했다.

  • repository의 raw → canonical → external-output 규칙
  • feature-application-port-usecase-contract의 D13 이유와 경계
  • canonical package-layout의 현재 상태, Gradle/ArchUnit 검사, 정적 분석 한계
  • logging decision record에서 SLF4J 선택 이유가 명시되지 않았다는 근거 경계

실행 검증은 재현 가능한 최소 corpus fixture로 수행했다. 실제 로컬 저장소 전체를 대상으로 한 end-to-end live provider run은 이 환경에서 수행하지 않았다.

12. 확인된 제한

  • local corpus 검색은 lexical ranking이며 동의어와 간접 표현을 놓칠 수 있다.
  • 검색된 chunk가 source-backed라는 사실과 해당 문장이 최종 글에서 정확하다는 사실은 다르다.
  • canonical과 branch-note가 충돌할 때 완전한 자동 authority 판정은 하지 않는다.
  • 한국어 rationale lint는 휴리스틱이며 false positive/negative 가능성이 있다.
  • STYLE001은 가까운 세 문단의 서수 시작을 탐지하는 휴리스틱이다. 전체 문체 품질이나 개별 서수 표현의 적합성을 증명하지 않는다.
  • LLM reviewer 합의는 사실 증명이 아니다.
  • 코드 예제와 명령은 실제 대상 시스템에서 별도로 실행해야 한다.
  • Windows PowerShell script는 제공하지만 이 Linux 검증 환경에서는 실행하지 않았다.
  • 실제 게시 전에는 프로젝트 소유자, 보안 담당자, 운영 담당자의 검토가 필요하다.

13. 재현 명령

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

bash scripts/verify.sh

실제 provider 환경 진단:

claridoc doctor --config config/pipeline.multi-agent.example.json
Reference in New Issue View Git Blame Copy Permalink