docs(review): require risk verification matrix before approval

This commit is contained in:
2026-10-08 11:45:25 +00:00
parent 6c27a9e07d
commit 2f2c630adc
@@ -46,6 +46,17 @@ Bootstrap 이후 code review는 canonical [Repository cache 운영 지침](../..
`terminal`로 Git diff를 확인하고 `read_file`로 모든 변경 파일과 필요한 주변 코드·테스트를 읽는다. 스타일 취향이나 승인 범위 밖의 기능을 필수 변경 요청으로 만들지 않는다. 계약 위반과 명세 자체의 결함을 구분한다.
**위험·검증 matrix:** 실행 검증 전에 승인된 계약과 변경·영향 경계에서 위험·검증 matrix를 작성한다. 파일 목록을 완료 checklist로 대신하지 않는다. 각 행에는 다음을 기록하며, 검토 중 새로 확인한 중요한 경계는 추가한다.
- **경계:** 관련 요구사항과 변경 로직·호출자.
- **위험·기대 동작:** 무엇이 잘못될 수 있고 무엇을 보장해야 하는가.
- **검증:** 필요한 정상·실패·경계·상태 전이 사례와 확인 방법.
- **승인 전 필수 여부:** 승인 전에 확인해야 하는지와 그 이유. 승인된 계약과 위험 분석으로 정하며, 결과가 불편하다는 이유로 사후에 필수 여부를 낮추지 않는다.
- **상태:** `통과 / 실패 / 미검증 / 비적용` 중 하나.
- **근거:** 코드 위치, 테스트·probe 결과 또는 재사용 근거의 참조. 정적 확인, CI·구현자 실행, reviewer 직접 실행과 재사용 근거를 구분하고 reviewed head·계약에 대한 적용 가능성과 한계를 명시한다.
`통과`는 기대 동작을 뒷받침하는 충분한 근거가 있음, `실패`는 기대 동작 위반이 확인됨, `미검증`은 미실행 또는 환경 오류·timeout 등으로 근거가 불충분함, `비적용`은 해당 경계가 적용되지 않는 구체적 이유가 있음을 뜻한다. 모든 행에 runtime test를 강제하지 않으며 위험에 따라 정적 확인이나 검증된 기존 근거를 사용할 수 있다. 환경·runner 오류를 제품 결함인 `실패`로 세지 않는다.
## 실행 검증과 기존 워크트리 사용
전체 테스트를 매번 재실행할 필요는 없다. Exact-head CI와 신뢰 가능한 실행 기록을 평가하고, 위험하거나 근거가 부족한 부분을 직접 검증한다. Command evidence에는 명령, exit code, 관련 출력, 환경과 source revision이 있어야 한다. 다른 revision의 기록은 전체 후속 diff와 실행 입력의 동일성을 증명한 경우에만 재사용하며 독립 실행과 구분한다.
@@ -62,13 +73,13 @@ Bootstrap 이후 code review는 canonical [Repository cache 운영 지침](../..
## 판정과 기록
- `approve`: 전체 diff, 관련 코드·테스트와 필요한 실행 근거를 검토했고 미해결 중요 결함이나 필수 검증 공백이 없다.
- `approve`: 전체 diff, 관련 코드·테스트와 필요한 실행 근거를 검토했고 미해결 중요 결함이나 필수 검증 공백이 없다. 승인 전 필수로 분류한 matrix 행은 모두 통과하거나 근거 있는 비적용이어야 한다. 필수 행에 실패·미검증 또는 설명 없는 비적용이 남으면 승인하지 않는다. 전체 파일 열람이나 전체 테스트 통과만으로 이 조건을 충족했다고 간주하지 않는다. 선택적 검증의 미완료는 한계로 보고하며 자동으로 변경 요청하지 않는다.
- `request_changes`: 승인된 범위 안의 미해결 중요 결함 또는 승인에 필요한 필수 검증 공백이 있다. 경미한 비차단 결함·무관한 기존 기술부채·선택적 개선만으로는 변경 요청하지 않는다.
- `blocked`: spec pass 부재·drift, 명세 모순 또는 안전한 검토를 막는 조건이 있다. 승인하지 않고 blocker를 보고한다.
Finding마다 `F-001` 같은 ID, 파일·행, 발생 조건, 영향·심각도, 확인 근거, 계약과의 관계 및 제한된 수정·재검증 방향을 기록한다. 확정 결함, 질문, 잔여 위험과 비차단 제안은 분리한다. 위임 시 exact head·계약 subset·파일 범위와 read-only 조건을 주고, main reviewer가 중요 지적을 직접 검증하며 최종 판정을 책임진다.
결과는 checkout 밖의 trusted workflow artifact에 한국어로 보존한다. Target, reviewed head, contract digest, spec review ID, findings, 실행 결과·한계와 verdict를 포함한다. SHA·path·명령은 원문을 유지하고 secret은 기록하지 않는다.
결과는 checkout 밖의 trusted workflow artifact에 한국어로 보존한다. Target, reviewed head, contract digest, spec review ID, findings, 실행 결과·한계와 verdict를 포함한다. 기존 결과 artifact에 위험·검증 matrix와 미검증 범위를 포함하며 별도 파일은 필수가 아니다. 최종 findings 게시 전에 계획된 검토 결과와 판정에 필요한 worker 결과를 main reviewer가 대조·통합하고 각 행의 상태를 확정한다. 일부 검토가 중단됐다면 partial/blocked 범위를 명시하고 전체 검토 완료로 표현하지 않는다. SHA·path·명령은 원문을 유지하고 secret은 기록하지 않는다.
## Native review 게시와 재검토