From bcd11fceabfe4723581b63b8ce0db8e274a1a610 Mon Sep 17 00:00:00 2001 From: gitea-spec-agent Date: Fri, 2 Oct 2026 07:24:43 +0000 Subject: [PATCH] docs(spec): strengthen discovery verification and replay --- .../skills/gitea-discovery-review/SKILL.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/harness/agents/spec/skills/gitea-discovery-review/SKILL.md b/harness/agents/spec/skills/gitea-discovery-review/SKILL.md index b277744..8d4ea09 100644 --- a/harness/agents/spec/skills/gitea-discovery-review/SKILL.md +++ b/harness/agents/spec/skills/gitea-discovery-review/SKILL.md @@ -39,8 +39,8 @@ Gitea 인증과 readback은 [Gitea authenticated access 운영 지침](../../../ ## OQ 검토 규칙 - 선택이 0개인 OQ는 미해결 상태로 유지한다. -- 선택이 정확히 1개인 OQ는 선택지의 의미를 확대하지 않고 사용자 결정으로 채택한다. -- 채택한 결정은 `확정된 결정`에 반영하고 필요한 `포함 범위`, `제외 범위`, `제약 조건`, `저장소 근거`, `문서 영향 및 산출물`에 일관되게 전파한 뒤 해당 OQ를 제거한다. +- 선택이 정확히 1개인 OQ는 선택지의 의미를 확대하지 않고 사용자 결정으로 채택한다. 사용자 선택을 기술적 전제가 성립한다는 증거로 취급하지 않는다. +- 채택한 결정은 `확정된 결정`에 반영하고 필요한 `포함 범위`, `제외 범위`, `제약 조건`, `저장소 근거`, `문서 영향 및 산출물`에 일관되게 전파한다. 핵심 기술적 전제를 확인하지 못하면 선택과 미검증 이유를 해당 OQ에 남기고 제거하지 않는다. 전파와 필요한 전제 확인이 끝난 OQ만 제거한다. - 선택된 결정이 기존 결정·범위·저장소 근거와 충돌하면 임의로 우선순위를 정하지 않는다. 충돌을 해소할 수 있는 새 OQ를 열거나, 선택지만으로 안전한 질문을 구성할 수 없으면 외부 write 없이 중단한다. - 사용자 prose 수정은 현재 문서 전체와 pinned source revision을 기준으로 검토한다. 이전 local artifact는 진단에만 사용할 수 있고 authoritative baseline으로 간주하지 않는다. - 검토 과정에서 새 사용자 결정이 필요하면 기존 최대 OQ 번호의 다음 ID를 사용한다. 삭제된 ID를 재사용하지 않으며 모든 선택지는 미선택 checkbox로 두고 추천안을 하나만 표시한다. @@ -49,14 +49,14 @@ Gitea 인증과 readback은 [Gitea authenticated access 운영 지침](../../../ ## 절차 -1. 요청에서 exact `owner`, `repository`, Issue 번호를 추출하고 단일 안전 경로 요소인지 검증한다. -2. canonical 순서로 Issue lock을 획득하고 authenticated Gitea API adapter로 review role의 stable account identity를 확인한다. +1. 요청에서 exact `owner`, `repository`, Issue 번호를 추출하고 단일 안전 경로 요소인지 검증한다. `operations/repository-cache.md`를 새로 읽고 canonical cache 경로를 계산·검증한다. +2. Authenticated Gitea API adapter로 review role의 stable account identity를 확인한다. 대상 cache가 없으면 `gitea-repository-cache-bootstrap`을 완료하고 bootstrap·repository lock이 모두 해제됐는지 확인한다. 기존 cache는 자동 초기화하지 않는다. Cache와 lock 경로의 안전성을 검증한 뒤 canonical Issue lock을 획득한다. 3. exact Issue와 전체 comments를 읽어 body, `updated_at`, title, state, labels, assignees, milestone과 comment baseline을 immutable snapshot으로 보존한다. 4. 이 스킬의 입력 승인 gate로 current body와 최초 authoring의 원본 provenance comment를 검증한다. 실패하면 comment와 body를 쓰지 않는다. -5. `operations/repository-cache.md`를 새로 읽고 Issue lock을 유지한 채 기존 cache를 검증한다. cache가 없으면 `gitea-repository-cache-bootstrap`을 사용한다. +5. Issue lock을 유지한 채 canonical 지침에 따라 기존 cache를 검증한다. 검증에 실패하면 자동 초기화하거나 복구하지 않고 중단한다. 6. repository lock을 canonical 순서로 획득해 origin을 fetch하고 Gitea default-branch SHA와 local ref가 정확히 일치하는 revision을 pin한다. 7. pinned SHA에서 current Discovery의 모든 저장소 근거, 다섯 후속 문서 경로, 요구사항 ID·파일명과 사용자 prose 수정의 사실성을 조사한다. 움직이는 branch나 다른 workspace를 근거로 사용하지 않는다. -8. 각 OQ의 선택 수를 판정하고 선택된 결정을 관련 모든 섹션에 전파한다. 새 모순·누락·정책 결정이 생기면 OQ 검토 규칙에 따라 새 OQ를 추가한다. +8. 각 OQ의 선택 수를 판정한다. 선택된 결정이 특정 API·dependency·runtime·배포 기능에 의존하면 pinned 저장소와 적용 버전의 공식 문서·소스를 조사해 지원 여부와 구현 경로를 확인한다. 조사만으로 판단할 수 없고 실행 실험이 필요하면 기술적 전제 검증을 미완료로 남긴다. 선택된 결정을 관련 모든 섹션에 전파하고, 새 모순·누락으로 새 사용자 결정이 필요할 때만 OQ 검토 규칙에 따라 새 OQ를 추가한다. 9. `문서 영향 및 산출물`을 README 정책에 따라 전부 다시 판정한다. 요구사항명세서의 exact ID·경로·제목·포함할 내용·제외할 내용과 다른 문서의 구체적 변경 계약을 현재 결정과 pinned SHA에 맞춘다. 10. 조사 종료 시 Gitea default-branch SHA와 local ref가 pinned SHA와 여전히 일치하는지 확인하고 repository lock을 해제한다. Issue lock은 유지한다. 11. trusted workflow directory에 revised body artifact를 만들고 marker, H2 순서, placeholder 부재, OQ ID·checkbox, 결정 전파, 문서 영향, repository evidence와 credential 부재를 검증한다. @@ -64,7 +64,7 @@ Gitea 인증과 readback은 [Gitea authenticated access 운영 지침](../../../ 13. write 직전에 Issue와 comments를 다시 읽는다. snapshot의 body·`updated_at` 또는 comment baseline이 drift했으면 외부 write 없이 중단한다. 14. snapshot의 body·`updated_at`·comment baseline과 비본문 필드가 불변일 때 revised body artifact의 exact bytes로 Issue body 하나만 교체한다. title, state, labels, assignees, milestone은 write payload에 포함하지 않는다. 15. Issue와 comments를 다시 읽어 body exact-match, 비본문 필드 불변성과 comment baseline 완전 불변을 검증한다. review는 어떤 comment도 추가·수정·삭제해서는 안 된다. -16. 동일 current state를 다시 판정해 추가 write가 없는 idempotent no-op인지 확인한 뒤 Issue lock을 해제한다. +16. 동일 pinned source revision과 readback한 현재 본문을 기준으로 내용 검토·정규화를 다시 적용해 결과가 현재 본문과 exact-match인지 확인한다. Replay에서는 외부 write를 수행하지 않으며, 불일치하면 replay 검증 실패로 보고한다. 확인 후 Issue lock을 해제한다. ## 금지 사항 @@ -84,12 +84,12 @@ Gitea 인증과 readback은 [Gitea authenticated access 운영 지침](../../../ - authenticated Gitea identity와 exact target - Issue/comment pre-write snapshot과 입력 승인 gate 결과 - cache 경로, bare·remote 검증, fetch와 pinned Gitea/local SHA -- 사용자 선택 OQ, 유지한 OQ, 제거한 OQ와 새로 연 OQ +- 사용자 선택 OQ, 유지한 OQ, 제거한 OQ와 새로 연 OQ 및 기술적 전제 검증 결과·근거·미검증 항목 - 사용자 prose 수정의 수용·조정·거부 결과와 근거 - 확정된 결정의 섹션별 전파 결과 - 다섯 후속 문서의 조치·exact 경로·변경 내용 검증 결과 - revised body exact readback과 비본문 필드 불변성 -- comment baseline 완전 불변과 replay no-op 결과 +- comment baseline 완전 불변과 내용 검토·정규화 재적용 결과의 exact-match 여부; 추가 조회의 불변 확인만으로 replay no-op 검증 완료를 보고하지 않는다. - partial 또는 fail-closed 상태 프로세스 exit나 API write 응답만으로 성공을 주장하지 않는다. Authoritative readback 또는 replay 검증이 하나라도 실패하면 completed로 보고하지 않는다.