# 품질 기준

점수를 계산하기 전에 hard gate를 먼저 검사한다. 사실을 바꾸거나 논증을 닫지 못한 문서는 표현이 매끄러워도 통과하지 않는다.

## 목차

- Hard gate와 점수 차원
- finding 심각도
- 독립 리뷰 계약
- lint와 final report
- 경로별 요구사항과 finalization 경계

## Hard gate

적용되는 항목 하나라도 실패하면 게시 진행을 멈춘다. 현재 계약 안에서 새 draft로 해결할 수 있으면 review verdict는 `revise`, source·사용자 결정·상류 구조 변경이 필요하면 `hold_for_review`다. 두 상태를 같은 의미로 쓰지 않는다.

1. `load_bearing: true`인 사실형 claim이 추적 가능한 근거와 `does_not_support` 경계를 가지며, 비사실 상태는 명확히 표시됐다.
2. 원문의 주장, 숫자, 코드, 인용문, citation, 정확한 identifier가 보존됐다. 승인된 정정은 별도로 기록한다.
3. 약속한 reader question이 모두 닫혔고 section dependency에 미해결 cycle이 없다.
4. current, example, conditional, recommended, future 상태를 혼동할 수 없다.
5. 경로별 필수 artifact가 존재하고 현재 입력에 대해 유효하며 schema를 통과한다.
6. standard와 deep은 서로의 결과를 읽지 않고 작성한 logic review와 reader review를 모두 가진다.
7. write/revise의 `final.md`가 확정·검토된 `07_draft.md`와 byte-identical하다. 어떤 수정도 drafting 단계로 반환한다.

## 점수 차원

적용되는 차원을 0~4로 판정한다.

| 점수 | 뜻 |
| --- | --- |
| 4 | 완전하고 정밀하며 독립 검증 가능하다. cosmetic 개선만 남았다. |
| 3 | 게시 가능하다. 작은 문제가 이해나 정확성을 방해하지 않는다. |
| 2 | 중요한 수정이 필요하다. material gap이 하나 이상 남았다. |
| 1 | major defect 때문에 신뢰하고 사용할 수 없다. |
| 0 | 누락, 모순, 또는 안전하지 않은 상태다. |

| 차원 | 검사 내용 |
| --- | --- |
| `logic` | 인과 진행, section prerequisite, decision rationale, end-to-end path, enforcement, limit, requirement closure |
| `reader_fit` | 선언된 audience, 정직한 prerequisite, easy-first 설명, reading path, comprehension outcome |
| `terminology` | first-use, acronym expansion, canonical alias, term budget, 정확한 implementation identifier |
| `evidence` | claim traceability, source precision, time scope, limitation, unsupported factual wording 부재 |
| `technical_fidelity` | claim, number, code, command, citation, interface, constraint의 원본 일치 |
| `artifact_integrity` | filename, schema, ownership, hash, route requirement, review independence |

이 점수표는 사람이 리뷰 관점을 정렬할 때 쓰는 참고 기준이다. 현재 `review.schema.json`과 `final-report.schema.json`에는 품질 점수 필드가 없으며 reviewer나 verifier는 계산하지 않은 차원 점수·overall percentage를 산출물에 만들지 않는다. 게시 gate는 실제 review, lint, schema, hash 결과로 판정한다.

## 심각도와 finding

- `critical`: 문서를 materially false, unsafe, unusable하게 만들 수 있다. 게시 차단.
- `high`: load-bearing reasoning 또는 target-reader comprehension을 깨뜨린다. 수정 전까지 차단.
- `medium`: 중심 결론을 무효화하지 않지만 friction, ambiguity, incomplete support를 만든다.
- `low`: 국소 polish, consistency, optional improvement다.

각 finding의 schema 필수 필드는 `id`, `severity`, `location`, `reader_impact`, `suggestion`이다. 선택 필드는 정확히 다음 이름과 형식을 쓴다.

- `evidence`: 관찰한 문장·독자 상태·대조 근거를 담은 비어 있지 않은 문자열
- `violated_rule`: 위반한 rule ID 또는 reference 항목을 담은 비어 있지 않은 문자열
- `owner`: `doc-evidence-curator | doc-logic-architect | doc-drafter`

`doc-finalizer`는 finding owner가 아니다. severity와 관계없이 finding을 고치려면 `doc-drafter` 또는 해당 상류 owner로 반환한다. `07_draft.md`나 상류 계약이 바뀌면 적용되는 review와 lint를 현재 hash로 다시 실행한다.

현재 schema에는 disposition, fixed, waiver 필드가 없다. reviewer와 verifier는 후속 결과를 직접 검증하지 않고 finding이 해결됐다고 만들지 않는다.

## 독립 리뷰 계약

### `08_logic_review.json`

logic reviewer는 causal order, closure, evidence alignment, technical fidelity를 검사한다. `08_reader_review.json`을 읽지 않고 `07_draft.md`를 수정하지 않는다.

적어도 다음 항목을 검사하고, 결함은 finding에 담는다.

- `core_claim`에서 section answer, evidence, closure로 가는 사슬
- 고아 section, 순환 논증, 원인 없는 solution
- claim status와 `does_not_support` 경계
- 숫자·코드·명령·인용·identifier 보존
- 결론 신규 주장
- verdict와 finding 목록

최상위에는 `schema_version`, `review_type: logic`, 현재 `07_draft.md`의 path/SHA-256을 담은 `document`, 실제로 읽은 upstream artifact hash 묶음인 `inputs`, `verdict`, `findings`가 필요하다. verdict는 `pass`, `revise`, `hold_for_review` 중 하나다. 실제 JSON 구조는 `{skill_dir}/schemas/review.schema.json`을 따른다.

### `08_reader_review.json`

reader reviewer는 explanation, vocabulary load, prerequisite, navigation, example transition을 검사한다. `08_logic_review.json`을 읽지 않고 `07_draft.md`를 수정하지 않는다.

적어도 다음 항목을 검사하고, 결함은 finding에 담는다.

- 선언하지 않은 선수지식
- first-use와 acronym expansion
- 문장 2개·문단 2개·절 7개의 term budget
- easy explanation이 formal term보다 먼저 나오는지
- example/current/recommended/future 전환 비용
- heading과 quick path의 탐색성
- verdict와 finding 목록

최상위에는 `schema_version`, `review_type: reader`, 현재 `07_draft.md`의 path/SHA-256을 담은 `document`, 실제로 읽은 upstream artifact hash 묶음인 `inputs`, `verdict`, `findings`가 필요하다. verdict는 `pass`, `revise`, `hold_for_review` 중 하나다. 실제 JSON 구조는 `{skill_dir}/schemas/review.schema.json`을 따른다.

두 review의 verdict는 다음 의미로만 사용한다. 한 review의 통과가 다른 review를 대신하지 않는다.

- `pass`: critical/high blocking finding이 없다. medium/low finding은 남을 수 있다.
- `revise`: 현재 상류 계약 안에서 Phase 3의 새 draft로 해결할 critical/high finding이 있다. finalizer 전에 draft를 수정하고 두 독립 review를 모두 다시 실행한다.
- `hold_for_review`: source, 사용자 결정, reader/evidence/logic 구조 변경이 필요해 Phase 3 수정만으로 진행할 수 없다.

`pass`와 critical/high finding의 조합, 또는 blocking finding이 없는 `revise`/`hold_for_review`는 invalid review artifact다. write/revise 경로의 finalizer는 적용되는 review가 모두 `pass`일 때만 실행한다. review-only 경로에서는 `revise`가 문서 진단 결과일 수 있으며 실행 실패를 뜻하지 않는다.

## `08_lint.json`

lint는 editorial judgment와 독립적인 기계 검사를 기록한다.

- reader contract·logic map·term ledger의 필수 구조와 상호 참조
- heading 단계, H1 수, unresolved placeholder, code fence balance, 닫히지 않은 HTML 주석, broken internal link
- logic section 순서·핵심 주장·필수 marker·dependency 기본 무결성
- 실제 본문에 정식 용어를 포함한 term first-use, alias·약어 순서, 용어 예산, 미등록 기술 용어 후보
- 기준 원문의 fenced·indented code block, 전체 inline code 식별자·명령·인수, http·https·ftp·ftps·file·mailto·ssh·git 절대 URI·Markdown link/citation target, 숫자·범위·단위·날짜·버전의 주변 의미 연결, 큰따옴표·blockquote 인용 보존과 final/draft 동일성

route별 required artifact, evidence의 source locator·premise·상태 경계, 전체 JSON Schema, 현재 hash, 두 review의 유형·대상·입력 hash 정합성은 최종 `verify_run.py`가 검사한다. 실제 reviewer가 상대 review를 읽지 않았다는 프로세스 독립성은 현재 산출물만으로 증명할 수 없으며, 오케스트레이터가 두 reviewer의 입력을 분리하는 실행 계약으로 지킨다. evidence gate는 lint rule catalog가 아니라 verifier의 `evidence-contract` check가 정본이다. verifier는 lint findings에서 severity별 합계와 `fail_on` verdict를 다시 계산하고, run/lint가 기록한 runtime contract·rules SHA-256을 현재 파일과 비교한다.

lint가 논리적으로 옳다고 선언해서는 안 된다. 각 check에 status와 evidence를 남기고, skip에는 이유가 필요하다. agent 자기평가와 lint가 충돌하면 lint를 따른다.

## `09_final_report.json`

이 파일은 deterministic verifier가 만들며 원 review를 덮어쓰지 않는다. 최상위 `verdict`는 **하네스 실행 verdict**이고, `document_verdict`는 **문서 판정**이다.

- write/revise에서 `verdict: pass`는 publish gate가 통과했다는 뜻이다.
- review-only에서 schema/hash/필수 artifact가 유효하고 두 review가 `pass | revise`, lint가 `pass | fail`이면 `verdict: pass`다. 나쁜 문서를 성공적으로 진단한 실행을 실패로 바꾸지 않는다.
- review-only의 `document_verdict`는 모두 통과하면 `pass`, review 하나가 `revise`이거나 lint가 `fail`이면 `revise`다.
- review `hold_for_review`, lint `input_error`, schema/hash/staleness 실패는 실행 `verdict: fail`과 `document_verdict: not_evaluated`다.

summary는 실제 검사에서 결정적으로 얻은 다음 값만 담는다.

- 전체 deterministic check의 passed/failed 수와 required artifact 목록
- 검증된 optional omission과 이유
- 유효한 lint artifact의 verdict, document hash, rules version과 SHA-256, 오류·경고·정보 finding 수, 최초 등장 순서대로 중복 제거한 rule ID, fidelity 객체, limitations 배열
- 유효한 review artifact별 verdict, document hash, upstream input hash 묶음, severity별 finding 수, finding ID
- 검증 뒤 run status

현재 verifier는 품질 점수, finding fixed/disposition, waiver 승인을 생성하지 않는다. 별도 검증 artifact가 없는데 이 값을 추측해 final report에 넣지 않는다. 현재 target이나 rules hash와 맞지 않는 lint/review도 요약하거나 문서 판정에 사용하지 않는다. write/revise 완료는 `verdict: pass`와 `document_verdict: pass`를 모두 요구한다. review-only 완료는 실행 `verdict: pass`를 요구하며 문서에는 `pass | revise` 진단을 그대로 보고한다.

## 경로별 요구사항

| 요구사항 | Light | Standard | Deep |
| --- | --- | --- | --- |
| evidence curation | 생략 가능 | 필수 | 필수 + staleness/limitation audit |
| logic review | 생략 가능 | 필수 | 필수 |
| reader review | 생략 가능 | 필수 | 필수 |
| lint와 fidelity check | 필수 | 필수 | 필수 |

optional은 조용히 건너뛰라는 뜻이 아니다. 검증 전에 생략한 정본 파일마다 별도 `{artifact, reason}` 항목을 `00_run.json.omissions`에 기록한다. verifier가 검증한 목록을 final report 요약에 복사한다.

## Finalization 경계

finalizer는 확정된 `07_draft.md`를 내용 변경 없이 byte-identical `final.md`로 복사하는 validation/publish gate다. review finding을 병합하지 않으며 local wording, 문장 순서, first-use, link처럼 작은 수정도 final 단계에서는 허용하지 않는다. critical/high는 물론 실제로 고치기로 한 medium/low finding이나 lint 오류도 Phase 3 draft 또는 해당 상류 owner로 반환한다. draft나 상류 계약을 갱신한 뒤 적용되는 독립 review를 현재 hash로 다시 수행하고, 새 draft를 그대로 복사한 뒤 lint를 다시 실행한다. light에서 review를 생략했더라도 draft를 고친 뒤 다시 lint한다.

final lint는 `--draft-baseline`의 변경률 상한 0과 verifier의 exact SHA-256 비교를 함께 사용한다. 따라서 semantic review 뒤 부정어 하나를 바꾸는 우회도 게시할 수 없다. post-final review artifact를 새로 만들지 않는다.

review verdict가 `revise`이면 finalizer를 호출하지 않는다. Phase 3 drafting으로 돌아가 새 `07_draft.md`를 만든 뒤 두 독립 review를 모두 다시 수행한다. source·사용자 결정·상류 계약 변경이 필요한 `hold_for_review`는 해당 blocker가 해결되기 전까지 Phase 3도 진행하지 않는다.