157 lines
12 KiB
Markdown
157 lines
12 KiB
Markdown
# 품질 기준
|
|
|
|
점수를 계산하기 전에 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도 진행하지 않는다.
|