fix(spec): enforce scope and evidence boundaries in reviews

2026-10-06 02:30:14 +00:00
parent a65171775c
commit 9cda9733c6
4 changed files with 107 additions and 5 deletions
@@ -1,7 +1,7 @@
 ---
 name: gitea-implementation-spec-review
 description: 승인된 계약에 대해 Gitea 구현 PR 적합성을 검토한다.
-version: 0.2.1
+version: 0.2.2
 author: genichin, Hermes Agent
 license: MIT
 platforms: [linux]
@@ -221,7 +221,7 @@ terminal(command="python3 harness/agents/spec/skills/gitea-implementation-spec-r
 8. Same-repository PR이면 head object도 cache에서 검증하고 exact base-to-head tree를 Gitea changed-file set·diff와 대조한다. Fork PR이면 target cache에 head object가 있다고 가정하지 않고 authoritative head repository·branch SHA와 Gitea changed-file set·diff를 대조한다. Diff 직렬화의 byte 차이만으로 실패시키지 않고 변경 경로와 exact base/head blob 및 hunk가 동일 변경을 나타내는지 검증한다. 임의 ref, checkout, clone 또는 worktree를 만들지 않는다.
 9. Repository lock을 해제하되 Issue lock은 유지한다.
 10. Acceptance matrix 작성 전에 구현자 실행 보고와 상세 실행 기록의 출처 및 확인 범위를 구분한다. Revision이 식별된 기존 evidence는 source revision과 reviewed head 사이 전체 diff·실행 입력 변경을 확인하고, 필수 검증별 재사용 가능 범위와 현재 head에 새로 결합해야 할 근거를 먼저 요약한다. 상세 기록이나 revision 정보의 부재만으로 새 검증 gate를 만들지 않는다. 재사용 여부는 위 Acceptance matrix의 기존 evidence binding 기준으로 판단하며 새 gate나 일괄 재실행 요구를 추가하지 않는다. 재검토에서는 이전 finding별 승인 계약 근거와 최소 보완 요청을 새 구현·evidence의 확인 위치에 대응하고, 해소 또는 잔여 사유를 기존 criterion의 `evidence`와 `reason`에 기록한다. 이미 충족된 검증을 source revision 차이만으로 다시 요구하지 않되, 변경 영향으로 새로 판정할 수 없어진 필수 조건은 그 근거와 최소 보완 범위를 특정한다. 이 초기 요약만으로 검토를 끝내지 않고 Approved Discovery에서 acceptance matrix를 만들고 모든 changed file, 문서, source, test와 exact-head-bound status evidence를 대응시킨다.
-11. 독립 code-review worker 결과가 있으면 exact head에 바인딩됐고 authoritative하게 읽을 수 있을 때만 보조 evidence로 사용한다. 그 결과를 spec verdict로 그대로 복사하지 않는다.
+11. 문서 검토 입력과 구조·의미 분리 절차로 trusted 계약·산출물별 의무표를 준비하고 모든 문서 의무를 대조한다. 위임 시 해당 입력 전체를 제공한다. 독립 code-review worker 결과가 있으면 exact head에 바인딩됐고 authoritative하게 읽을 수 있을 때만 보조 evidence로 사용한다. 그 결과를 spec verdict로 그대로 복사하지 않는다.
 12. Verdict 규칙으로 하나의 strict result artifact와 canonical review body를 trusted workflow directory에 생성한다.
 13. Exact key/type, duplicate key, marker field, digest, deterministic correlation, criterion cardinality, path binding, verdict/state 조합, credential 부재와 render → parse → render byte equality를 검증한다.
 14. 여기까지는 read-only preflight다. Exact review 요청이 native review write 권한을 부여하지 않았거나 preflight가 완전하지 않으면 종료하며 review create 또는 다른 mutation을 수행하지 않는다.
@@ -240,12 +240,24 @@ terminal(command="python3 harness/agents/spec/skills/gitea-implementation-spec-r

 모든 종료 경로(정상·no-op·검증 실패·API 오류·예외)는 획득한 lock을 `finally`에서 역순 해제하고 non-blocking 재획득·해제를 확인한다. Write 후 응답과 authoritative readback snapshot은 판정 assertion 전에 credential 없이 먼저 보존하고, 검증 실패 사유는 별도로 기록한다. 불확실한 POST는 절차 19만 적용하고 후속 write를 중단한다. 종료 시 final report를 authoritative 결과로 확정하며 native review 제출 상태와 절차 전체 상태를 분리한다. Progress artifact를 사용했다면 최종 상태·review ID·잔여 오류를 갱신하거나 stage·timestamp·final report 참조를 갖춘 중간 snapshot임을 명시한다. Cleanup 실패도 final report에 남기고 완료로 보고하지 않는다.

+## 문서 검토 입력과 구조·의미 분리
+
+문서 검토를 main이 수행하거나 delegate에 위임하기 전에 다음 입력을 trusted workflow에 준비한다. 이 준비는 제품 저장소의 새 산출물이나 result schema 변경을 요구하지 않는다.
+
+- Exact reviewed head와 immutable 문서 snapshot 및 승인된 Discovery의 산출물 계약.
+- [Trusted requirements README](../../../../docs/requirements/README.md)와 [TEMPLATE](../../../../docs/requirements/TEMPLATE.md)의 exact 내용 또는 byte parity가 검증된 trusted bundle. 읽은 정본 경로와 revision 또는 digest를 기록하고 실제 내용을 delegate context로 제공한다. 대상 저장소 README/TEMPLATE를 작성 정책으로 대신 사용하지 않는다.
+- 산출물별 의무표: exact 경로, 신규·갱신·영향 없음, 승인 근거, 필수 구조 항목, 필수 의미·동작 계약, 확인할 문서·test·evidence와 이전 finding 해소 여부.
+- 기존 요구사항 갱신이면 pinned baseline 문서 및 전체 AC의 보존·승인된 변경 대응. 재검토이면 이전 finding의 승인 근거와 최소 보완 요청.
+- 실행 evidence의 출처·재사용 가능 범위·확인 한계. 별도 CI·새 evidence 경로·추가 browser 실패 조합을 승인 근거 없이 필수 조건으로 만들지 않는다.
+
+문서 delegate에는 위 입력을 빠짐없이 전달한다. 입력이 부족하면 main이 보완하거나 직접 검토하며 delegate의 PASS를 최종 판정으로 채택하지 않는다. 구조 적합성(metadata·필수 섹션·요구사항/AC 블록·추적성)과 의미 적합성(승인 계약의 보존·충족·누락)을 각각 판정하고 exact section·line 및 참조 test 근거를 반환하게 한다. 구조 통과만으로 의미를 승인하거나 대체로 맞는 내용으로 필수 구조 누락을 무시하지 않는다. 문구·배치 차이 또는 다른 섹션·기존 test로 보존된 계약의 반복 기재 부재만으로 의미 누락을 만들지 않는다. Main은 모든 의무표 항목과 delegate finding을 pinned 문서에 직접 대조하고 기존 acceptance matrix의 contract·evidence·reason에 반영한다.
+
 ## 위임 규칙

 - Main spec-agent는 contract extraction, acceptance matrix, verdict와 외부 write에 책임을 진다.
 - Bounded diff 분할, criterion별 evidence 수집과 일반 코드 품질 검토는 독립 delegate에 병렬 위임할 수 있다.
 - Delegate에는 exact PR head, approved contract subset, changed-file allowlist와 read-only 범위를 제공한다. 적용되는 계약의 초기 작성·PR 생성 후 갱신 시점과 특정 구현 수단의 강제 여부를 함께 전달하며, 계약을 충족하는 구현 세부를 새로운 요구사항·범위 초과로 오인하지 않도록 한다.
- 문서 delegate에는 산출물별 필수 계약 항목과 section·line 대응을 요구하고 evidence-only source binding의 검증 결과 및 허용된 실행 evidence 범위를 전달한다. 계약이 요구하지 않은 CI 성공·기존 승인·모든 실패 조합의 browser test를 새 필수 조건으로 만들지 않으며, main은 위 Acceptance matrix 기준으로 누락과 각 변경 요청의 승인 근거를 직접 재검증한다.
+- 문서 delegate에는 위 문서 검토 입력 전체를 제공하고 구조·의미의 별도 판정 및 산출물별 필수 계약 항목과 section·line 대응을 요구하고 evidence-only source binding의 검증 결과 및 허용된 실행 evidence 범위를 전달한다. 계약이 요구하지 않은 CI 성공·기존 승인·모든 실패 조합의 browser test를 새 필수 조건으로 만들지 않으며, main은 위 Acceptance matrix 기준으로 누락과 각 변경 요청의 승인 근거를 직접 재검증한다.
 - Delegate가 Gitea write, source 수정, Git commit·push·merge, lock·cache·worktree 변경을 수행하지 못하게 한다.
 - Delegate summary는 evidence가 아니다. Main agent가 cited path, diff, status와 test evidence를 직접 확인한다.