donghyeon.kang/document-haness

Fork 0

Files

T

DongHyeonka d6f78f92a0 init: document-haness 설계

2026-07-23 17:52:22 +09:00

12 KiB

Raw Blame History

품질 기준

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

Hard gate

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

load_bearing: true인 사실형 claim이 추적 가능한 근거와 does_not_support 경계를 가지며, 비사실 상태는 명확히 표시됐다.
원문의 주장, 숫자, 코드, 인용문, citation, 정확한 identifier가 보존됐다. 승인된 정정은 별도로 기록한다.
약속한 reader question이 모두 닫혔고 section dependency에 미해결 cycle이 없다.
current, example, conditional, recommended, future 상태를 혼동할 수 없다.
경로별 필수 artifact가 존재하고 현재 입력에 대해 유효하며 schema를 통과한다.
standard와 deep은 서로의 결과를 읽지 않고 작성한 logic review와 reader review를 모두 가진다.
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도 진행하지 않는다.

12 KiB Raw Blame History