Initialize gitea-agent harness

harness/agents/impl/skills/gitea-issue-implementation/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: gitea-issue-implementation
+description: 승인된 Gitea Issue를 구현·검증하고 Gitea PR로 전달한다.
+version: 0.2.0
+author: genichin, Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [gitea, implementation, worktree, testing, pull-request]
+    related_skills: []
+---
+
+# Gitea Issue Implementation
+
+승인된 Gitea Discovery와 pinned repository revision을 근거로 Issue별 persistent worktree에서 요구 문서, source와 test를 구현하고 검증한 뒤 Issue 전용 branch와 Gitea PR로 전달한다. Repository cache와 worktree 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md), 문서 형식은 `docs/` 아래 각 문서 유형의 README와 TEMPLATE만 정본으로 사용한다. Exact Issue 구현 요청은 승인된 범위의 commit, 일반 push와 PR 생성을 승인하지만 merge, force-push, Issue close, release 또는 deployment를 승인하지 않는다.
+
+## 사용 시점
+
+다음과 같이 exact repository와 Issue를 지정해 구현을 요청받았을 때 사용한다.
+
+```text
+<owner>/<repository> 이슈 #<number>를 구현하라
+```
+
+이 요청은 현재 authoritative Issue body를 구현 대상으로 승인하고 다음 작업을 허용한다.
+
+- canonical Issue worktree 생성 또는 유효한 기존 worktree 재사용
+- 승인된 범위의 요구 문서, source, test와 repository 설정 수정
+- synthetic fixture와 test-only credential을 사용한 build, test, lint와 정적 검증
+- 구현 결과와 검증 evidence의 local 보존
+- 승인된 diff만 포함하는 local commit 생성
+- Issue 전용 remote branch의 신규 생성과 non-force push
+- Target repository write 권한이 없을 때 authenticated identity 소유 fork 생성·재사용과 cross-repository PR 전달
+- default branch를 base로 하는 Gitea PR 생성과 생성 결과 readback
+- PR 번호 확정 후 요구 문서의 `구현 PR: 미정`을 실제 번호 또는 URL로 갱신하는 후속 commit과 non-force push
+
+다음 작업은 요청 문구에 별도로 명시되지 않으면 승인되지 않는다.
+
+- force-push, rebase, amend 또는 다른 history rewrite
+- default branch나 기존 비전용 remote branch로의 push
+- PR merge, close, review, reviewer 지정 또는 승인 범위를 바꾸는 수정
+- Issue comment, body, title, state, label, assignee 또는 milestone 변경
+- release, package 또는 deployment 게시
+
+Discovery 작성·검토, 미해결 요구사항 선택, 단순 repository 조사 또는 이미 구현된 변경의 독립 PR review에는 사용하지 않는다.
+
+## 정본과 승인 gate
+
+구현을 시작하려면 현재 Issue body가 다음을 모두 충족해야 한다.
+
+- 첫 줄이 exact `<!-- gitea-agent:discovery-draft/v2 -->` marker다.
+- 요약, 문제, 포함 범위, 제외 범위, 제약 조건, 확정된 결정, 저장소 근거, 문서 영향 및 산출물, 미해결 질문을 판독할 수 있다.
+- 미해결 질문이 exact `없음`이거나 동등하게 미해결 결정이 없음을 명확히 나타낸다.
+- pinned source revision이 full commit SHA로 하나만 확정돼 있다.
+- 구현 산출물의 exact 경로와 요구사항 ID를 안전하게 결정할 수 있다.
+- 서로 충돌하는 결정, 선택되지 않은 선택지, placeholder 또는 실제 credential이 없다.
+
+정확한 구현 요청은 해당 시점의 유효한 current body에 대한 구현 승인이다. 그러나 미해결 질문, malformed Discovery, 결정 충돌, 불명확한 범위 또는 credential 노출이 있으면 사용자의 의도를 추측하지 않고 worktree나 repository file을 변경하지 않는다.
+
+Issue body와 `updated_at`을 immutable approval snapshot으로 보존한다. body의 exact UTF-8 SHA-256 digest를 `terminal`로 계산하며 식별자나 digest를 임의로 정규화하지 않는다. 구현 중 authoritative Issue가 snapshot과 달라지면 새 내용을 자동 채택하지 않고 drift로 중단한다.
+
+## Lock과 권한 경계
+
+모든 cache, lock, path, credential, worktree 생성·재사용·제거 규칙은 작업할 때마다 `read_file`로 `operations/repository-cache.md`를 새로 읽어 적용한다. 이 스킬의 요약이 canonical 문서를 완화하거나 대체하지 않는다.
+
+- Issue workflow 전체에서 exact `issue-<number>.lock`을 유지한다.
+- Cache 초기화·fetch·ref 검증과 worktree 등록 변경에는 canonical 순서로 repository lock을 추가 획득한다.
+- 일반 편집과 test에는 Issue lock만 유지한다.
+- 다른 Issue worktree나 다른 checkout을 읽기·수정·정리하지 않는다.
+- lock을 획득할 수 없거나 현재 실행이 lock 순서를 증명할 수 없으면 fail-closed한다.
+- 종료, 오류와 중단 경로에서 현재 실행이 획득한 lock만 역순으로 해제한다.
+
+## 절차
+
+### 1. Target과 identity 고정
+
+1. 요청에서 exact `owner`, `repository`와 Issue 번호를 추출하고 각각 canonical identifier 규칙으로 검증한다.
+2. Issue lock을 획득한다.
+3. Gitea MCP `get_me`로 현재 impl role identity를 확인한다.
+4. Gitea MCP로 exact repository metadata, default branch와 SHA, Issue 전체 필드와 전체 comment baseline을 읽는다.
+5. title, body, state, labels, assignees, milestone, `updated_at`, comment cardinality와 body digest를 immutable approval snapshot으로 기록한다.
+
+완료 조건: authenticated identity, exact target과 재현 가능한 approval snapshot이 모두 존재한다.
+
+### 2. Discovery와 산출물 계약 추출
+
+1. 승인 gate로 current body를 검증한다.
+2. 포함 범위, 제외 범위, 제약 조건과 확정된 결정을 중복 없이 추출한다.
+3. 각 문서의 조치, exact path와 필수 내용을 추출한다. `영향 없음`인 문서를 생성하지 않는다.
+4. 사용자 관찰 가능 동작, 실패 동작, 보안 불변조건, 호환성 조건과 외부 write 경계를 acceptance matrix로 만든다.
+5. 각 acceptance criterion에 예정된 문서, source 위치와 검증 test를 연결한다. 연결할 수 없는 criterion이 있으면 구현 전에 중단한다.
+
+완료 조건: 모든 확정된 결정과 산출물이 acceptance matrix의 한 항목 이상에 대응하고, 제외 범위가 구현 항목에 포함되지 않는다.
+
+### 3. Cache 검증과 base 결정
+
+1. `operations/repository-cache.md`를 새로 읽는다.
+2. Canonical 절차로 cache를 초기화하거나 기존 cache를 검증한다. malformed cache를 삭제, reset, chmod, chown 또는 다른 repository로 교체하지 않는다.
+3. Issue lock 아래 repository lock을 획득해 exact origin에서 prune/fetch하고 Gitea default branch SHA와 local ref 일치를 검증한다.
+4. Discovery pinned SHA가 cache에 존재하는 commit object이고 Issue가 주장한 revision과 exact-match하는지 확인한다.
+5. Pinned SHA와 current default branch SHA가 같으면 이를 base로 확정한다.
+6. 두 SHA가 다르면 pinned revision부터 current default branch까지의 commit과 변경 파일을 조사한다. 변경이 Discovery 근거, 요구 문서 ID·경로, 대상 API, test contract 또는 acceptance criteria를 무효화하지 않는다는 근거가 있을 때만 current default branch SHA를 base로 사용한다.
+7. 변경이 material하거나 요구사항과 충돌하거나 안전하게 판정할 수 없으면 worktree를 만들거나 수정하지 않고 renewed Discovery가 필요하다고 보고한다.
+
+완료 조건: Gitea와 local에서 확인된 full base SHA, 선택 근거와 pinned-to-base 차이 판정이 기록돼 있다.
+
+### 4. Worktree 생성 또는 재사용
+
+1. Approval snapshot이 아직 current Issue와 exact-match하는지 다시 읽는다.
+2. `operations/repository-cache.md`의 admission gate를 그대로 적용한다.
+3. 신규 worktree는 canonical path에서 exact base SHA의 detached HEAD로 생성하고 Issue 용도로 lock한다.
+4. `gitea-agent.worktree/v1` state를 canonical 방식으로 게시한다.
+5. 기존 worktree는 state identity, Git registration, common directory, detached·locked 상태, base ancestry, dirty 상태와 미완료 Git operation을 모두 검증한 뒤 재사용한다.
+6. 기존 worktree의 파일, untracked state 또는 commit을 reset, clean, rebase, checkout, switch 또는 삭제로 자동 복구하지 않는다.
+7. Repository lock을 해제하고 Issue lock은 유지한다.
+
+완료 조건: exact worktree path, base SHA, current HEAD, detached·locked 상태와 approval snapshot binding이 canonical 검증을 통과한다.
+
+### 5. Repository baseline 조사
+
+1. `search_files`, `read_file`과 worktree를 대상으로 한 read-only `terminal` Git 명령으로 tree, build 설정, test runner, formatter, lint와 기존 문서 구조를 조사한다.
+2. Discovery가 언급한 모든 source와 test 경로를 실제 base에서 읽는다. 읽지 않은 파일을 근거로 구현을 설계하지 않는다.
+3. Repository가 선언한 canonical install과 test 명령을 찾는다. 임의의 전역 package 설치나 운영 credential을 사용하지 않는다.
+4. 관련 기존 test를 수정 전 실행하고 exit code와 실패 내용을 보존한다.
+5. Baseline 실패가 변경 대상과 관련되거나 새 구현의 판정을 방해하면 수정하지 않고 blocker로 보고한다. 명백히 무관한 기존 실패라면 범위와 evidence를 기록하고 영향받는 test를 별도로 판정한다.
+
+완료 조건: 변경 대상의 현재 동작, dependency direction, test command와 baseline 결과가 실제 output으로 확인됐다.
+
+### 6. 요구 문서 작성
+
+Discovery가 `신규 작성` 또는 `수정`으로 판정한 문서만 작성한다.
+
+1. 요구사항명세서는 `read_file`로 harness의 [요구사항 작성 방법](../../../../docs/requirements/README.md)과 [요구사항 템플릿](../../../../docs/requirements/TEMPLATE.md)을 새로 읽고 Discovery가 지정한 target repository의 exact ID·경로로 작성한다.
+2. 데이터 모델은 영향이 있을 때만 harness의 [데이터 모델 작성 방법](../../../../docs/data-model/README.md)과 [데이터 모델 템플릿](../../../../docs/data-model/TEMPLATE.md)을 적용한다.
+3. 인터페이스 계약은 영향이 있을 때 harness의 [인터페이스 계약 작성 방법](../../../../docs/interface-contract/README.md)과 [인터페이스 계약 템플릿](../../../../docs/interface-contract/TEMPLATE.md)을 적용한다.
+4. 프로젝트 구조는 영향이 있을 때 harness의 [프로젝트 구조 작성 방법](../../../../docs/project-structure/README.md)과 [프로젝트 구조 템플릿](../../../../docs/project-structure/TEMPLATE.md)을 적용한다.
+5. 런타임 흐름은 영향이 있을 때 harness의 [런타임 흐름 작성 방법](../../../../docs/runtime-flow/README.md)과 [런타임 흐름 템플릿](../../../../docs/runtime-flow/TEMPLATE.md)을 적용한다.
+6. Requirement frontmatter는 canonical `gitea-agent.requirement/v1` 계약을 만족하고 status를 `approved`로 기록한다. 구현 PR이 아직 없으면 `미정`을 유지하고 번호를 추측하지 않는다.
+7. 모든 placeholder, 작성 안내 문구, 실제 credential과 확인되지 않은 경로를 제거한다.
+
+완료 조건: Discovery의 문서 영향 판정과 생성·수정된 문서 집합이 정확히 일치하고 각 문서가 해당 README와 TEMPLATE 검증을 통과한다.
+
+### 7. Test-first 구현
+
+1. Acceptance matrix에서 변경 전 실패해야 하는 정상, 실패, 경계와 보안 test를 먼저 추가한다.
+2. 새 test가 의도한 이유로 실패하는지 실행해 확인한다. 환경 오류나 잘못된 fixture 실패를 RED evidence로 사용하지 않는다.
+3. 기존 architecture와 dependency direction을 유지하는 최소 source 변경으로 test를 통과시킨다.
+4. 실패 경로가 외부 상태를 변경하지 않는지 검증한다.
+5. 실제 운영 데이터, password, token 또는 credential을 test와 fixture에 사용하지 않는다.
+6. Timing, concurrency 또는 retry 조건은 clock·sleep 의존성을 주입하거나 통제 가능한 seam으로 unit test하되, Discovery가 실제 elapsed-time 보장을 요구하면 실제 통합 경로 test도 유지한다.
+7. 관련 test를 작은 단위로 반복한 뒤 전체 관련 suite를 실행한다.
+
+완료 조건: 각 acceptance criterion에 실제로 실행된 test 또는 판정 가능한 문서·정적 검증 evidence가 연결돼 있다.
+
+### 8. 통합 검증과 독립 검토
+
+1. Repository가 요구하는 formatter, lint, type check, build와 test suite를 실제 실행한다.
+2. Base-to-worktree diff를 읽고 모든 변경 파일을 acceptance matrix와 대응한다.
+3. 범위 밖 변경, debug artifact, generated drift, credential material, query parameter secret, test-only bypass와 운영 데이터가 없는지 검사한다.
+4. 새 dependency가 있다면 필요성과 lockfile·deployment 반영을 검증한다.
+5. 설정 예시에는 secret 이름과 용도만 기록하고 실제 값을 넣지 않는다.
+6. 독립 검토가 유용하면 `delegate_task`로 bounded reviewer를 사용한다. Reviewer에게 exact worktree path, base SHA, Issue snapshot, acceptance matrix와 검증 명령을 전달하고 Gitea write, Git cleanup, commit과 push를 금지한다.
+7. Main agent가 reviewer 지적을 직접 재현하고 유효한 문제만 수정한 뒤 영향을 받은 검증을 다시 실행한다.
+
+완료 조건: 모든 modified file이 승인된 산출물로 설명되고, 실행한 quality gate와 unresolved finding이 명확하다.
+
+### 9. Drift 확인, commit과 PR 전달
+
+1. Gitea Issue와 comments를 다시 읽어 approval snapshot의 body, `updated_at`과 comment baseline drift를 확인한다.
+2. Repository lock 아래 origin을 다시 fetch하고 Gitea default branch SHA와 local ref를 확인한다.
+3. Default branch가 base 이후 전진했으면 자동 merge, rebase 또는 history rewrite하지 않는다. 새 변경이 구현과 충돌하지 않는지 판정할 수 없으면 delivery-ready로 보고하지 않는다.
+4. Worktree의 base SHA, final HEAD, staged·unstaged·untracked 상태, 미완료 Git operation과 test 결과를 기록한다.
+5. Branch 이름은 repository convention이 있으면 이를 따르고, 없으면 `gitea-agent/issue-<number>-<short-slug>`처럼 deterministic Issue 전용 이름을 사용한다. Gitea와 remote에서 동일 이름의 branch와 열린 PR을 먼저 조회해 중복 생성하지 않는다.
+6. 승인된 modified·untracked file을 exact allowlist로 stage하고 staged diff를 다시 읽는다. 범위 밖 파일, credential, generated artifact 또는 예상하지 못한 삭제가 있으면 commit하지 않는다.
+7. Repository convention에 맞는 non-amended commit을 생성하고 base ancestry, commit tree와 worktree 상태를 검증한다.
+8. Issue 전용 branch가 없으면 final commit을 가리키도록 생성하고, 있으면 현재 작업이 소유한 branch이며 fast-forward 가능한 경우에만 갱신한다. Default branch에는 직접 push하지 않고 force-push하지 않는다. Canonical cache의 mirror remote 설정을 변경하지 말고 push할 때 explicit repository URL과 refspec을 사용한다.
+9. Target repository write 권한이 없으면 같은 push를 반복하지 않는다. Authenticated identity가 fork를 생성할 수 있으면 기존 fork·동명 branch·PR 유무와 fork parent/base SHA를 검증한 뒤 fork의 Issue 전용 branch로 non-force push하고 cross-repository PR을 사용한다. Fork도 쓸 수 없으면 permission blocker와 local commit SHA를 보고한다.
+10. Remote readback으로 branch owner, repository, branch SHA가 local commit SHA와 exact-match하는지 확인한다.
+11. Default branch를 base로 PR을 생성한다. 제목은 Issue를 식별하고, 본문에는 `Closes #<number>`, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. PR 생성 자체로 Issue state를 변경하지 않는다.
+12. PR 번호를 얻은 뒤 요구사항 문서의 `구현 PR: 미정`을 실제 PR 번호 또는 URL로 교체하고, 문서 검증과 관련 test를 재실행해 별도 commit으로 같은 branch에 non-force push한다.
+13. Gitea에서 PR details, base branch, head repository·branch·SHA, state, changed files와 commit을 다시 읽는다. 최종 remote head SHA가 최종 local commit SHA와 일치할 때만 전달 완료로 판정한다.
+14. PR 생성 또는 후속 push가 부분 실패하면 blind retry하거나 중복 PR을 만들지 않는다. 이미 생성된 fork·branch·PR과 local commit의 exact 상태 및 안전한 복구 지점을 보고한다.
+
+완료 조건: Issue와 source drift, final worktree 상태와 실행 결과가 fresh readback으로 확인되고, 열린 Gitea PR의 base·head와 remote head SHA가 검증된 최종 local commit에 exact-match한다.
+
+## 위임 규칙
+
+Main agent는 구현 범위와 최종 결과에 책임을 진다. 독립적인 repository 조사, test 작성, 특정 모듈 구현, 보안 검토 또는 실패 분석은 병렬 위임할 수 있지만 다음을 지킨다.
+
+- Delegate에 Issue body 전체가 아니라 필요한 확정 계약, exact worktree path와 금지된 side effect를 명시한다.
+- 같은 파일을 병렬로 수정하는 worker를 만들지 않는다.
+- Delegate가 Gitea write, lock 변경, worktree 생성·제거, commit, push 또는 reset을 수행하지 못하게 한다.
+- Delegate의 성공 주장을 evidence로 간주하지 않고 main agent가 diff와 test output을 직접 확인한다.
+- 외부 side effect는 main agent만 수행하고 즉시 authoritative readback한다.
+
+## 주의점과 금지 사항
+
+- 미해결 질문이나 충돌하는 결정을 임의로 선택하지 않는다.
+- Issue body에 없는 기능, migration, refactor 또는 dependency를 편의상 추가하지 않는다.
+- Moving branch나 stale cache를 구현 근거로 사용하지 않는다.
+- Bare mirror에 구현용 local branch를 만들지 않는다.
+- 다른 worktree의 변경을 가져오거나 정리하지 않는다.
+- 기존 dirty state를 reset, clean, stash, checkout 또는 force remove하지 않는다.
+- test를 통과시키기 위해 production security gate, validation 또는 실패 경로를 약화하지 않는다.
+- 실제 credential, 운영 DB 또는 사용자 금융 데이터를 test나 artifact에 사용하지 않는다.
+- 실행하지 않은 test, 읽지 않은 파일 또는 확인하지 않은 Gitea 상태를 성공 evidence로 보고하지 않는다.
+- Issue 구현 요청 범위를 벗어난 commit·push·PR 변경, force-push, merge, Issue 변경, release 또는 deployment를 수행하지 않는다.
+- 실패하거나 불확실한 외부 write를 blind retry하지 않는다.
+
+## 검증 및 보고
+
+완료 보고에는 다음을 구분해 포함한다.
+
+- authenticated Gitea identity와 exact target
+- approval snapshot의 Issue `updated_at`, body digest와 미해결 질문 검증
+- cache path, bare·remote 검증, fetch 결과와 Gitea/local SHA
+- Discovery pinned SHA, selected base SHA와 차이 판정
+- worktree path, 신규 생성 또는 재사용, detached·locked 상태와 final HEAD
+- 요구 문서별 조치, exact path와 canonical template 검증
+- acceptance criterion별 구현 위치와 test evidence
+- baseline, targeted와 full-suite 명령의 실제 exit 결과
+- modified file 전체와 범위 내 변경 근거
+- staged, unstaged, untracked, 미완료 Git operation, local commit과 remote branch SHA
+- Issue와 default branch의 최종 drift readback
+- PR 번호·URL·base·head·state와 PR head SHA readback
+- 수행한 commit·push·PR write와 수행하지 않은 merge·Issue·release write
+- blocker, 기존 실패, unresolved risk 또는 partial 상태
+
+파일 작성, process exit, test 일부 통과, local commit 또는 delegate 보고만으로 완료를 주장하지 않는다. 모든 승인된 산출물이 worktree에 존재하고 acceptance matrix, 실제 test output, final diff, remote branch와 열린 PR의 fresh Gitea readback이 일치할 때만 구현 완료로 판정한다.

harness/agents/release/skills/gitea-release/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: gitea-release
+description: 승인된 Gitea 버전을 준비·태깅하고 산출물을 게시한다.
+version: 0.1.0
+author: genichin, Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [gitea, release, worktree, tag, artifact]
+    related_skills: [gitea-repository-cache-bootstrap]
+---
+
+# Gitea Release
+
+Gitea repository cache를 사용해 버전 준비, 검증, 태깅과 프로젝트별 산출물 게시를 수행한다. Cache 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md)을 정본으로 사용한다.
+
+## 사용 시점
+
+- exact `owner/repository`의 새 버전 준비를 요청받았을 때
+- 준비된 commit을 태깅하고 승인된 산출물을 게시하도록 요청받았을 때
+- 기존 릴리즈의 tag, commit과 게시 산출물을 검증할 때
+
+Issue 구현, PR merge, 임의 버전 선택, 기존 tag 이동, artifact 덮어쓰기 또는 deployment에는 사용하지 않는다.
+
+## 책임 분리
+
+### 공통 릴리즈 처리
+
+이 스킬이 담당한다.
+
+- repository cache 검증과 fetch
+- release lock과 worktree 관리
+- 버전 변경 파일 제한
+- 간단한 준비 검증
+- local commit 생성과 commit tree 검증
+- 승인된 commit에 tag 생성·push
+- 프로젝트별 게시 절차 호출
+- 원격 tag와 artifact readback
+- 성공한 worktree 정리
+
+### 프로젝트별 처리
+
+Target repository의 release contract가 담당한다.
+
+- version source와 함께 변경할 lockfile
+- test, lint와 build 명령
+- artifact 종류와 이름
+- 대상 platform과 build context
+- registry, package namespace와 인증 secret 이름
+- smoke test와 게시 명령
+- digest, checksum 또는 provenance 검증
+
+Release contract가 없거나 모호하면 기존 workflow, build metadata와 문서를 읽어 확인된 사실만 보고한다. 이미지 이름, registry, credential, 명령 또는 artifact를 추측하지 않는다.
+
+## 승인 계약
+
+### 준비 승인
+
+버전 변경과 local commit을 시작하려면 다음이 필요하다.
+
+- exact `owner/repository`
+- exact version과 tag
+- 버전 파일 변경에 대한 명시적 승인
+
+Agent는 버전을 선택, 증가, 정규화 또는 교체하지 않는다.
+
+### 게시 승인
+
+Tag 또는 artifact를 외부에 게시하려면 다음이 필요하다.
+
+- exact `owner/repository`
+- exact version과 tag
+- 준비된 full commit SHA
+- exact artifact와 게시 대상
+
+브랜치명, 축약 SHA, `HEAD`, moving tag 또는 unstated default는 게시 승인이 아니다.
+
+## Release worktree 모델
+
+Repository마다 동시에 하나의 release workflow만 허용한다.
+
+```text
+/opt/data/gitea-agent/repositories/<owner>/<repository>/
+├── locks/release.lock
+└── worktrees/release/
+    ├── state.json
+    └── checkout/
+```
+
+- `release.lock`을 전체 workflow 동안 유지한다.
+- Cache fetch, worktree 등록 변경과 제거에는 `release.lock → repository.lock` 순서로 획득한다.
+- Worktree는 확인된 원격 default-branch full SHA의 detached HEAD로 생성하고 lock한다.
+- 기존 release worktree를 reset, clean, rebase, checkout, force-remove 또는 덮어쓰지 않는다.
+- 실패한 release worktree는 증거 보존을 위해 자동 제거하지 않는다.
+
+`state.json`에는 최소한 schema `gitea-agent.release-worktree/v1`, repository identity, base SHA, requested version·tag, prepared commit SHA와 단계 상태를 기록한다. Credential, PID 또는 secret 값은 기록하지 않는다.
+
+## 절차
+
+### 1. Target과 cache 확인
+
+1. 요청의 repository, version, tag와 승인 범위를 추출한다.
+2. Gitea MCP로 authenticated identity, repository metadata, default branch와 SHA를 읽는다.
+3. `operations/repository-cache.md`에 따라 cache를 검증하거나 초기화한다.
+4. Release lock 아래 repository lock을 획득해 exact origin을 prune/fetch한다.
+5. Gitea default-branch SHA와 local mirror ref 일치를 확인한다.
+
+완료 조건: authoritative repository identity와 local cache가 같은 full SHA를 가리킨다.
+
+### 2. Release worktree 생성
+
+1. 기존 release worktree, Git registration과 state를 함께 조사한다.
+2. 대상이 모두 없을 때만 exact default-branch SHA에서 detached worktree를 만든다.
+3. Worktree를 release 용도로 lock하고 `state.json`을 원자적으로 기록한다.
+4. HEAD, detached 상태, common Git directory와 clean 상태를 다시 확인한다.
+
+완료 조건: release worktree가 확인된 base SHA에서 clean·detached·locked 상태다.
+
+### 3. 프로젝트 계약 조사
+
+1. `search_files`와 `read_file`로 version metadata, lockfile, test, build, 기존 workflow와 release 문서를 읽는다.
+2. Version 변경 파일, 준비 검증과 게시 adapter를 구분한다.
+3. 정확한 게시 대상이나 credential 가용성을 확인할 수 없으면 수정 전에 중단한다.
+
+완료 조건: 변경 파일 allowlist, 준비 검증 명령과 프로젝트별 게시 절차가 명확하다.
+
+### 4. 버전 변경과 준비 commit
+
+1. 승인된 exact version만 allowlist 파일에 반영한다.
+2. Project-defined 준비 test와 정적 검사를 실행한다.
+3. 수정·미추적 파일 전체를 검사하고 allowlist 밖의 변경이 있으면 중단한다.
+4. Exact path만 stage하고 staged diff, secret, 삭제와 whitespace 오류를 검토한다.
+5. Non-amended local commit을 생성한다.
+6. Commit의 parent, tree, version·tag 일치와 clean worktree를 검증한다.
+7. `state.json`에 prepared full SHA와 검증 결과를 기록한다.
+
+완료 조건: 승인된 버전 변경만 포함한 하나의 검증된 local commit이 존재한다.
+
+### 5. 게시 gate
+
+다음을 모두 확인한다.
+
+- 게시 승인이 exact prepared full SHA를 포함한다.
+- Gitea와 local에서 동일 tag가 존재하지 않는다.
+- 동일 artifact version 또는 image tag가 존재하지 않는다.
+- 필요한 credential과 target이 확인됐다.
+- 필수 test와 check가 exact prepared commit에서 성공했다.
+- Worktree HEAD와 tree가 준비 검증 이후 바뀌지 않았다.
+
+하나라도 불명확하면 외부 상태를 변경하지 않는다.
+
+### 6. Tag와 프로젝트별 게시
+
+1. 승인된 exact tag를 prepared commit에 생성한다.
+2. Explicit remote URL과 refspec으로 신규 tag만 non-force push한다.
+3. Gitea readback으로 remote tag target이 prepared SHA와 일치하는지 확인한다.
+4. Project release contract의 build, smoke test와 publish 절차를 그대로 실행한다.
+5. 승인된 artifact와 immutable commit-derived tag만 게시한다.
+
+`latest`, 추가 channel, 추정 artifact 또는 기존 tag를 게시·이동·덮어쓰지 않는다.
+
+### 7. 권위 있는 검증
+
+- Gitea remote tag target을 다시 읽는다.
+- 게시 artifact의 version, digest 또는 checksum을 authoritative target에서 읽는다.
+- Artifact provenance가 prepared SHA와 일치하는지 확인한다.
+- 여러 tag를 게시했다면 모두 같은 승인 artifact를 가리키는지 확인한다.
+- Gitea Release가 별도 승인됐다면 target, metadata와 attachments를 다시 읽는다.
+
+완료 조건: remote tag와 모든 승인 산출물이 prepared SHA에 연결되고 immutable identifier로 확인된다.
+
+### 8. 정리
+
+모든 readback이 성공하고 worktree가 clean하며 prepared commit이 remote tag로 보존된 경우에만 release worktree를 제거한다.
+
+1. Release lock과 repository lock을 유지한다.
+2. Worktree lock을 해제하고 Git operation으로 registration과 checkout을 제거한다.
+3. `state.json`과 빈 release directory만 제거한다.
+4. Worktree와 registration 부재를 확인한 뒤 lock을 역순으로 해제한다.
+
+Partial failure, dirty state, 미게시 commit 또는 불확실한 readback에서는 정리하지 않는다.
+
+## 실패 처리
+
+- Version, tag, commit, artifact 또는 target을 추측하지 않는다.
+- 기존 tag를 force-update, 삭제 또는 재생성하지 않는다.
+- 기존 artifact를 덮어쓰거나 삭제하지 않는다.
+- 실패한 build를 임의 변경으로 수리하지 않는다.
+- External write 실패를 blind retry하지 않는다.
+- 부분 성공 상태와 안전한 재개 지점을 보존하고 사용자 결정을 요청한다.
+
+## 검증 및 보고
+
+완료 보고에는 다음을 포함한다.
+
+- repository와 authenticated identity
+- base, prepared와 remote tag full SHA
+- exact version과 tag
+- 변경 파일과 commit
+- 실행한 test·build·smoke 명령의 실제 결과
+- 게시 artifact의 exact 이름과 immutable digest 또는 checksum
+- 수행한 외부 write와 authoritative readback
+- worktree 정리 또는 보존 상태
+- blocker와 partial failure
+
+명령 성공만으로 릴리즈 완료를 주장하지 않는다. Remote tag와 모든 승인 산출물의 fresh readback이 일치할 때만 완료다.

harness/agents/spec/skills/gitea-discovery-authoring/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: gitea-discovery-authoring
+description: Gitea Issue의 Discovery 초안을 작성하고 게시한다.
+version: 0.3.4
+author: genichin, Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [gitea, discovery, specification, authoring]
+    related_skills: [gitea-repository-cache-bootstrap]
+---
+
+# Gitea Discovery Authoring
+
+Gitea Issue 원본과 저장소 근거를 조사해 Discovery 초안을 작성하고 Issue 본문에 게시한다. 작성 규칙은 [Discovery 작성 방법](../../../../docs/discovery/README.md), 문서 구조는 [Discovery 템플릿](../../../../docs/discovery/TEMPLATE.md)만 정본으로 사용하며 이 스킬에 복제하거나 임의로 확장하지 않는다.
+
+## 사용 시점
+
+다음과 같이 정확한 저장소와 Issue를 지정해 Discovery 초안 작성을 요청할 때 사용한다.
+
+```text
+<owner>/<repository>의 이슈 #<number>에 대해 discovery 초안을 작성하라
+```
+
+이 요청은 원본 본문의 comment 보존과 Discovery 초안으로의 본문 교체를 승인한다. 다른 comment, label, assignee, title, state, milestone 또는 repository write는 승인하지 않는다.
+
+요구사항 문서, 구현 계획 또는 PR review 작성에는 사용하지 않는다.
+
+## Repository cache admission gate
+
+Repository cache의 구조와 운영 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md)만 정본으로 사용한다. 작업할 때마다 이 문서를 새로 읽고 상세 규칙을 이 스킬에 복제하거나 완화하지 않는다.
+
+Discovery 초안을 작성하기 전에 repository cache admission gate를 반드시 통과한다. 대상 cache가 없거나 초기화되지 않았다면 `gitea-repository-cache-bootstrap` 스킬로 초기화한다. 초기화 여부와 관계없이 canonical origin에서 cache를 갱신하고, 갱신 후 다시 읽은 Gitea authoritative default-branch SHA와 local ref SHA가 정확히 일치해야 한다. 일치한 SHA를 pinned source revision으로 고정하며, gate가 실패하면 초안을 작성하지 않는다.
+
+## 절차
+
+1. 요청에서 exact `owner`, `repository`, Issue 번호를 추출하고 형식을 검증한다.
+2. Issue lock을 획득한 상태에서 Gitea MCP `get_me`로 spec-agent identity를 확인한다.
+3. Gitea MCP로 exact repository metadata, Issue 전체 내용과 전체 comment baseline을 읽는다. Issue title, body, state, labels, assignees, milestone과 `updated_at`을 immutable pre-write snapshot으로 보존한다.
+4. `operations/repository-cache.md`를 새로 읽는다. Issue lock을 유지한 채 대상 cache가 없거나 초기화되지 않았다면 `gitea-repository-cache-bootstrap` 스킬을 사용한다.
+5. bootstrap 완료 여부와 관계없이 canonical 순서에 따라 repository lock을 획득한다. path, bare 상태와 remote identity를 검증한 뒤 authoritative origin에서 prune/fetch한다. fetch 후 Gitea default branch와 SHA를 다시 읽고 local ref가 exact SHA와 일치하는지 확인하여 pinned source revision으로 기록한다. 어느 단계든 실패하면 repository lock을 해제하고 외부 write와 Discovery 작성을 수행하지 않는다.
+6. `read_file`로 `docs/discovery/README.md`와 `docs/discovery/TEMPLATE.md`를 새로 읽는다.
+7. repository lock을 유지한 채 Issue 원본과 pinned repository SHA의 tree 및 파일을 조사한다. 움직이는 branch 이름 대신 exact pinned SHA를 사용하고, `git --git-dir=<path>/repository.git`의 read-only 명령 또는 이에 상응하는 안전한 reader만 사용하며 조사한 경로와 SHA를 기록한다. README가 정한 후속 문서의 exact 경로 존재 여부와 기존 요구사항명세서의 ID·파일명을 함께 조사한다.
+8. 조사 종료 시 Gitea default-branch SHA와 local ref를 다시 읽어 pinned SHA와 모두 일치하는지 확인하고 repository lock을 해제한다. Issue lock은 전체 Issue workflow가 끝날 때까지 유지한다.
+9. README의 작성 규칙과 TEMPLATE의 visible 구조를 그대로 적용해 Discovery body artifact를 작성한다. `문서 영향 및 산출물`은 README가 정한 모든 문서 유형을 빠짐없이 판정하고 문서별 필수 내용을 구현 에이전트가 추가 설계 없이 작성할 수 있을 정도로 구체화한다. 요구사항명세서는 pinned SHA에서 충돌 여부를 확인한 exact 문서 ID·경로·제목·포함할 내용·제외할 내용을 기록한다. 모든 `${...}` placeholder를 교체하고 TEMPLATE에 없는 hidden state, marker 또는 metadata를 추가하지 않는다.
+10. body artifact의 첫 marker, 섹션 순서·제목, placeholder 부재, `문서 영향 및 산출물`의 문서 유형·순서·조치·경로·변경 내용·근거와 문서별 필수 내용 및 모든 저장소 근거가 pinned SHA에서 확인됐는지 검증한다. 신규 요구사항명세서의 경로에 `NNN`, `<slug>` 또는 다른 미확정 값이 남아 있거나 ID 충돌·형식 오류를 해소할 수 없으면 외부 write 없이 중단한다.
+11. write 직전에 Issue와 comments를 다시 읽는다. pre-write snapshot의 body와 `updated_at`이 달라졌거나 comment baseline이 drift했으면 중단한다.
+12. 아래의 단순 원본 보존 comment 형식으로 exact comment artifact를 만들고 한 번 작성한 뒤, 곧바로 comment 목록에서 authoritative readback한다.
+13. comment readback 직후 Issue와 comments를 다시 읽어 post-comment snapshot을 만든다. body와 비본문 필드가 pre-write snapshot과 같고 comments가 baseline과 exact 신규 comment 하나로만 구성돼야 한다. 다르면 body를 변경하지 않고 partial 상태로 중단한다.
+14. 보존 comment가 정확히 확인된 경우에만 Issue body 하나만 Discovery 초안으로 교체한다. provider가 조건부 update를 지원하면 post-comment `updated_at` 또는 ETag를 precondition으로 사용한다. 지원하지 않으면 Issue lock 아래에서 13번 read 직후 write하며 title, state, labels, assignees, milestone 등 다른 필드는 write payload에 포함하지 않는다.
+15. 동일 Issue를 다시 읽어 body가 초안과 정확히 일치하고 다른 snapshot 필드가 변경되지 않았는지 확인한다. comments도 다시 읽어 보존 comment가 정확히 하나인지 확인한다.
+
+## 원본 보존 comment
+
+comment는 다음 형식을 사용한다. `<original-body>`에는 write 직전 Gitea에서 읽은 원본 body를 변형 없이 넣는다.
+
+```text
+<!-- gitea-agent:discovery-origin/v1 owner=<owner> repository=<repository> issue=<number> body-sha256=<sha256> -->
+## Discovery 작성 전 이슈 원본
+
+<original-body>
+```
+
+`body-sha256`은 Gitea가 반환한 원본 body의 UTF-8 bytes에 대해 `terminal`로 계산한다. 게시 후 comment의 author, target marker, body digest와 `<original-body>` exact bytes를 모두 검증한다. 이 comment metadata를 Issue body에 포함하지 않는다.
+
+- 원본 comment와 Discovery body는 trusted workflow directory에 artifact로 먼저 작성하고 실제 write payload와 exact-match하는지 확인한다.
+- Discovery body는 TEMPLATE에서 만든 artifact의 exact bytes를 전송하고 즉시 Gitea MCP readback으로 검증한다.
+- 다른 checkout, workspace, installed package 또는 외부 renderer를 import하지 않는다.
+- credential 값은 출력하거나 artifact에 기록하지 않는다.
+
+## 재실행과 부분 실패
+
+- 동일 target에 유효한 원본 보존 comment가 이미 있고 현재 body가 유효한 Discovery 초안이면 새 comment나 body write 없이 완료 상태를 readback한다.
+- comment write 응답이 timeout 또는 오류이면 재시도하지 않는다. comment 목록을 한 번 조정해 baseline 대비 exact 신규 comment 하나만 확인될 때만 계속한다.
+- 원본 comment는 게시됐지만 Issue body가 아직 원본과 같다면 partial 상태로 간주한다. exact marker, digest, author와 원본 일치를 검증한 뒤 기존 comment를 재사용하여 body 교체만 재개한다.
+- 원본 comment가 여러 개이거나 marker/digest가 잘못됐거나 현재 body가 원본 및 유효한 Discovery 어느 쪽과도 일치하지 않으면 자동 복구하지 않는다.
+- Issue body update가 불확실하면 다시 update하지 않고 exact Issue를 한 번 readback해 결과를 판정한다.
+
+## 금지 사항
+
+- 현재 README와 TEMPLATE의 규칙을 이 스킬에서 재정의하지 않는다.
+- repository cache의 dirty, malformed 또는 drift 상태를 자동 삭제·초기화·덮어쓰기하지 않는다.
+- stale하거나 Gitea authoritative SHA와 일치하지 않는 cache를 Discovery 근거로 사용하지 않는다.
+- 읽지 않은 파일이나 실행하지 않은 검증을 저장소 근거로 제시하지 않는다.
+- 추천안을 사용자의 확정된 결정으로 표현하지 않는다.
+- credential, token 또는 환경변수 값을 출력하거나 산출물에 포함하지 않는다.
+- 원본 보존 comment 확인 전에 Issue body를 교체하지 않는다.
+- 성공 여부가 불확실한 외부 write를 blind retry하지 않는다.
+
+## 검증 및 보고
+
+완료 전에 다음을 모두 확인하고 구분해 보고한다.
+
+- authenticated MCP identity
+- repository cache 경로, 신규 초기화 또는 기존 재사용 여부, fetch 결과, bare 상태, pinned branch와 Gitea/local SHA 일치
+- 원본 Issue snapshot과 comment baseline
+- 조사한 repository evidence
+- Discovery 문서 정본 검증 결과
+- `문서 영향 및 산출물`의 문서별 조치와 검증 결과
+- 원본 보존 comment ID, author, marker와 digest readback
+- Issue body exact readback과 비본문 필드 불변성
+- 최종 comment cardinality와 중복 원본 comment 부재
+- dry-run/local 검증과 실제 Gitea write 결과
+
+프로세스 exit나 MCP write 응답만으로 성공을 주장하지 않는다. authoritative readback이 하나라도 실패하면 partial 또는 failure로 보고한다.

harness/agents/spec/skills/gitea-discovery-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: gitea-discovery-review
+description: 수정된 Gitea Discovery를 검토하고 정규화한다.
+version: 0.2.0
+author: genichin, Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [gitea, discovery, review, specification]
+    related_skills: [gitea-discovery-authoring, gitea-repository-cache-bootstrap]
+---
+
+# Gitea Discovery Review
+
+사용자가 Gitea Issue의 Discovery body에서 OQ를 선택하거나 본문을 수정한 뒤 그 수정본을 검토해 달라고 요청할 때 사용한다. 현재 Issue body를 review candidate의 정본으로 삼아 결정 전파, 모순 제거, 후속 OQ와 문서 영향 재평가를 수행한다. Discovery 승인, label·assignee 변경, 구현 handoff 또는 후속 문서·source 작성은 수행하지 않는다.
+
+작성 규칙은 [Discovery 작성 방법](../../../../docs/discovery/README.md), visible 구조는 [Discovery 템플릿](../../../../docs/discovery/TEMPLATE.md), cache와 lock 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md)만 정본으로 사용한다.
+
+## 사용 시점
+
+다음과 같이 exact repository와 Issue의 수정된 Discovery 검토를 요청받았을 때 사용한다.
+
+```text
+<owner>/<repository> 이슈 #<number>의 수정된 discovery를 검토하라
+```
+
+이 요청은 실제 정규화가 필요할 때 Issue body만 교체하는 것을 승인한다. 검토 전 candidate를 comment로 보존하지 않으며 comment, title, state, label, assignee, milestone, repository file 또는 source write는 승인하지 않는다. 최초 Discovery 작성에는 `gitea-discovery-authoring`을 사용한다.
+
+## 입력 승인 gate
+
+- body 첫 줄이 exact `<!-- gitea-agent:discovery-draft/v2 -->`이고 TEMPLATE의 H2 순서가 정확해야 한다.
+- 최초 Discovery authoring의 원본 provenance comment는 authoring 계약에 맞는 exact comment 하나여야 하며 review는 이를 읽기만 한다.
+- OQ ID는 고유하고 증가해야 하며 각 선택지는 checkbox여야 한다.
+- OQ마다 선택된 항목이 0개 또는 1개여야 한다. 2개 이상이면 사용자의 결정을 추측하지 않고 외부 write 없이 중단한다.
+- credential, token, password 또는 secret의 실제 값이 body에 포함된 것으로 의심되면 comment를 포함한 어떤 외부 write도 수행하지 않는다.
+- malformed marker·섹션·comment·OQ 또는 identity가 불명확하면 자동 복구하지 않는다.
+
+## OQ 검토 규칙
+
+- 선택이 0개인 OQ는 미해결 상태로 유지한다.
+- 선택이 정확히 1개인 OQ는 선택지의 의미를 확대하지 않고 사용자 결정으로 채택한다.
+- 채택한 결정은 `확정된 결정`에 반영하고 필요한 `포함 범위`, `제외 범위`, `제약 조건`, `저장소 근거`, `문서 영향 및 산출물`에 일관되게 전파한 뒤 해당 OQ를 제거한다.
+- 선택된 결정이 기존 결정·범위·저장소 근거와 충돌하면 임의로 우선순위를 정하지 않는다. 충돌을 해소할 수 있는 새 OQ를 열거나, 선택지만으로 안전한 질문을 구성할 수 없으면 외부 write 없이 중단한다.
+- 사용자 prose 수정은 현재 문서 전체와 pinned source revision을 기준으로 검토한다. 이전 local artifact는 진단에만 사용할 수 있고 authoritative baseline으로 간주하지 않는다.
+- 검토 과정에서 새 사용자 결정이 필요하면 기존 최대 OQ 번호의 다음 ID를 사용한다. 삭제된 ID를 재사용하지 않으며 모든 선택지는 미선택 checkbox로 두고 추천안을 하나만 표시한다.
+- 미해결 OQ가 없으면 `## 미해결 질문`의 본문을 exact `없음`으로 쓴다.
+- 추천안을 사용자가 선택한 결정처럼 기록하거나 사용자 대신 checkbox를 선택하지 않는다.
+
+## 절차
+
+1. 요청에서 exact `owner`, `repository`, Issue 번호를 추출하고 단일 안전 경로 요소인지 검증한다.
+2. canonical 순서로 Issue lock을 획득하고 Gitea MCP `get_me`로 review role identity를 확인한다.
+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`을 사용한다.
+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를 추가한다.
+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 부재를 검증한다.
+12. revised body가 current body와 exact-match하면 comment와 body write 없이 no-op으로 종료한다.
+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을 해제한다.
+
+## 금지 사항
+
+- 사용자의 미선택 OQ를 자동으로 선택하지 않는다.
+- 선택된 결정을 근거 없이 확장하거나 다른 OQ의 답으로 간주하지 않는다.
+- review 중 Issue를 승인하거나 구현 상태로 전환하지 않는다.
+- 검토 전 body 또는 revised body를 comment로 보존하지 않고 어떤 comment도 추가·수정·삭제하지 않는다.
+- label, assignee, title, state, milestone 또는 최초 authoring의 원본 provenance comment를 변경하지 않는다.
+- 요구사항명세서, data-model, interface-contract, project-structure, runtime-flow 또는 source를 직접 작성하지 않는다.
+- stale cache, unpinned source, 다른 workspace, installed package 또는 이전 local artifact를 authoritative 근거로 사용하지 않는다.
+- 불확실한 Gitea write를 blind retry하지 않는다.
+
+## 검증 및 보고
+
+완료 전에 다음을 구분해 보고한다.
+
+- authenticated Gitea identity와 exact target
+- Issue/comment pre-write snapshot과 입력 승인 gate 결과
+- cache 경로, bare·remote 검증, fetch와 pinned Gitea/local SHA
+- 사용자 선택 OQ, 유지한 OQ, 제거한 OQ와 새로 연 OQ
+- 사용자 prose 수정의 수용·조정·거부 결과와 근거
+- 확정된 결정의 섹션별 전파 결과
+- 다섯 후속 문서의 조치·exact 경로·변경 내용 검증 결과
+- revised body exact readback과 비본문 필드 불변성
+- comment baseline 완전 불변과 replay no-op 결과
+- partial 또는 fail-closed 상태
+
+프로세스 exit나 MCP write 응답만으로 성공을 주장하지 않는다. authoritative readback 또는 replay 검증이 하나라도 실패하면 completed로 보고하지 않는다.

harness/agents/spec/skills/gitea-implementation-spec-review/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: gitea-implementation-spec-review
+description: 승인된 계약에 대해 Gitea 구현 PR 적합성을 검토한다.
+version: 0.1.0
+author: genichin, Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [gitea, implementation, pull-request, review, specification]
+    related_skills: [gitea-discovery-review, gitea-repository-cache-bootstrap]
+---
+
+# Gitea Implementation Specification Review
+
+`gitea-impl-agent`가 만든 Gitea PR을 승인된 Discovery 계약과 대조해 요구사항 충족, 범위 누락·초과, acceptance criteria와 test evidence의 대응을 판정한다. 검토 결과는 구현 branch의 Git commit이나 Issue comment가 아니라 검토한 immutable PR head commit에 바인딩된 native Gitea review로 기록한다. 일반 코드 품질·보안 검토, source 수정, Discovery 변경과 merge는 수행하지 않는다.
+
+## 사용 시점
+
+다음과 같이 exact repository, source Issue와 PR을 지정해 구현 적합성 검토를 요청받았을 때 사용한다.
+
+```text
+<owner>/<repository> Issue #<issue-number> 구현 PR #<pull-number>을 명세 적합성 기준으로 검토하라
+```
+
+이 요청은 아래 조건을 모두 충족할 때 exact PR head에 native review 하나를 작성하는 것만 승인한다.
+
+- `approve` → `APPROVED`
+- `request_changes` → `REQUEST_CHANGES`
+- `blocked_spec` → `COMMENT`
+
+Issue comment·body·title·state·label·assignee·milestone, repository file, branch, commit, merge, release와 deployment write는 승인하지 않는다.
+
+## 역할과 검토 경계
+
+- Spec-agent는 current authoritative Discovery의 확정 계약을 해석하고 구현의 적합성을 판정한다.
+- Spec-agent는 review 중 새 요구사항·acceptance criterion·설계 선택을 만들거나 기존 계약을 구현에 맞춰 완화하지 않는다.
+- 일반적인 코드 스타일, 광범위한 보안 탐색, 성능 최적화와 유지보수성은 독립 code-review worker의 책임이다. 다만 계약 위반으로 이어지는 논리·보안 문제는 spec finding으로 다룬다.
+- 구현 결함과 명세 결함을 분리한다. 명확한 계약 위반은 `request_changes`, 계약 자체의 모순·누락 때문에 판정할 수 없으면 `blocked_spec`이다.
+- Review worker를 위임하더라도 main spec-agent가 authoritative evidence, 최종 verdict, native review write와 readback에 책임을 진다.
+- Native review는 spec-agent 전용 Gitea MCP connection으로만 작성한다. 해당 connection의 `get_me` stable account ID를 snapshot에 기록하고 ambient REST token, impl-agent credential 또는 다른 profile credential로 fallback하지 않는다.
+- 전용 MCP connection이나 expected stable account identity를 검증할 수 없으면 read-only 분석과 native review write를 모두 완료로 보고하지 않는다.
+
+## 입력 승인 gate
+
+다음 조건을 모두 충족하지 않으면 native review를 작성하지 않는다.
+
+- `owner`, `repository`, Issue 번호와 PR 번호가 각각 안전한 canonical identifier다.
+- Gitea MCP `get_me`로 확인한 stable account ID가 spec review role이며 PR author·implementation role의 stable account ID와 다르다. Transport별 login 표시가 달라도 account ID가 같으면 같은 identity로 판정한다.
+- PR이 open이고 exact target repository의 default branch를 base로 하며 head repository·branch와 40자리 full head SHA를 authoritative하게 식별할 수 있다. Fork PR이면 head repository metadata와 branch SHA를 별도로 읽어 PR head와 일치시킨다.
+- PR body에 source Issue와 결합되는 exact `Closes #<issue-number>`가 하나만 있고 다른 close directive가 없다.
+- Source Issue body 첫 줄이 exact `<!-- gitea-agent:discovery-draft/v2 -->`이며 canonical H2 구조를 만족한다.
+- `## 미해결 질문`이 exact `없음`이고 선택되지 않은 checkbox, placeholder, 충돌 결정 또는 실제 credential이 없다.
+- Discovery pinned revision, exact 산출물 경로와 요구사항 ID를 판독할 수 있다.
+- PR base·head, commits, changed files, bounded diff, status와 기존 native reviews를 authoritative API에서 읽을 수 있다.
+- Changed-file pagination, review pagination 또는 diff가 incomplete·truncated·ambiguous하지 않다.
+- 동일 spec-agent가 같은 head·contract에 이미 게시한 canonical review가 0개 또는 정확히 1개다. 둘 이상이거나 서로 다른 결과가 있으면 fail-closed한다.
+
+## 계약 snapshot과 binding
+
+1. Source Issue의 number, author, title, body, state, labels, assignees, milestone, `created_at`, `updated_at`, 전체 comments와 body SHA-256을 immutable contract snapshot으로 기록한다.
+2. PR number, state, base repository·branch·SHA, head repository·branch·SHA, author, body, head commit object, changed-file set와 기존 review baseline을 immutable PR snapshot으로 기록한다.
+3. `contract-sha256`은 authoritative Issue body의 exact UTF-8 bytes에 대해 계산한다.
+4. Review는 exact `owner/repository`, Issue, PR, `head`, `contract-sha256`와 `result-sha256`에 결합한다. `correlation`은 이 deduplication identity의 canonical NUL-delimited UTF-8 bytes를 SHA-256한 deterministic 64자리 hex이며 run마다 바꾸지 않는다.
+5. Issue body·`updated_at`, PR head, base target 또는 review baseline이 write 전에 drift하면 결과를 새 상태에 자동 적용하지 않고 중단한다.
+
+## Acceptance matrix
+
+Discovery의 포함 범위, 제외 범위, 제약 조건, 확정된 결정과 `문서 영향 및 산출물`에서 판정 가능한 항목을 추출한다. 각 항목을 다음 필드로 기록한다.
+
+```text
+criterion: <stable local identifier or requirement/AC ID>
+contract: <approved contract text>
+implementation_paths: [<changed path>...]
+test_paths: [<changed or existing test path>...]
+evidence: <diff, file, test/status or document evidence>
+result: satisfied | unsatisfied | indeterminate
+reason: <bounded Korean explanation>
+```
+
+- 모든 확정 결정과 필수 산출물은 criterion 하나 이상에 대응해야 한다.
+- 모든 changed file은 criterion, 필수 supporting change 또는 검증 evidence로 설명돼야 한다.
+- `영향 없음`으로 판정된 문서·schema·domain 영역의 변경은 범위 초과 후보로 조사한다.
+- PR의 요구사항 문서는 Discovery가 배정한 ID·경로·제목을 유지하고 `gitea-agent.requirement/v1` canonical 계약, Issue `#<issue-number>`와 구현 PR traceability를 만족해야 한다.
+- Acceptance criterion마다 구현 위치와 test·status·정적 evidence가 있어야 한다. PR body의 test 성공 주장만으로 실제 file·status 또는 실행 evidence를 대체하지 않는다.
+- CI/status evidence는 exact reviewed head SHA에 결합돼야 한다. Command evidence는 command, exit code, 판정에 필요한 output, 실행 환경과 source revision의 trusted provenance를 포함해야 하며 하나라도 없으면 `indeterminate`다.
+- 실패 경로, fail-closed, no-call·no-write boundary와 credential 비노출 조건은 positive-path test만으로 충족됐다고 판정하지 않는다.
+- 현재 harness에 spec-review 전용 clean worktree 계약이 없으므로 구현 Issue worktree를 spec role로 재사용하거나 임시 clone·checkout을 만들지 않는다. 독립 실행이 필요한 criterion에 authoritative CI/status 또는 신뢰 가능한 실행 evidence가 없으면 이를 숨기지 않고 `indeterminate`로 기록한다.
+
+## Verdict 규칙
+
+### `approve`
+
+다음을 모두 충족할 때만 사용한다.
+
+- 모든 필수 criterion이 `satisfied`다.
+- `unsatisfied`와 `indeterminate`가 없다.
+- 모든 changed file이 승인 범위로 설명된다.
+- 필수 문서, source, 설정과 test가 존재한다.
+- PR head와 contract snapshot에 drift가 없다.
+
+Native review state는 `APPROVED`다.
+
+### `request_changes`
+
+명확한 승인 계약에 대해 다음 중 하나 이상이 확인될 때 사용한다.
+
+- 필수 기능·문서·test 또는 acceptance criterion 누락
+- 구현 동작이 확정 결정, fail-closed 또는 no-call·no-write boundary를 위반
+- 제외 범위 구현 또는 설명할 수 없는 범위 초과 변경
+- 잘못된 요구사항 ID·경로·traceability
+- 실행 또는 정적 evidence가 계약 실패를 증명
+
+Native review state는 `REQUEST_CHANGES`다. 변경 요청은 기존 계약의 exact 근거를 인용하고 새로운 요구사항을 만들지 않는다.
+
+### `blocked_spec`
+
+다음처럼 구현만 수정해서는 안전하게 해결할 수 없을 때 사용한다.
+
+- 승인 계약 내부의 모순
+- 둘 이상의 비호환 구현 중 선택이 필요한 누락 결정
+- acceptance criterion이 판정 불가능하거나 source reality와 충돌
+- 현재 contract snapshot의 provenance 또는 scope가 불명확
+
+Native review state는 `COMMENT`다. 구현 에이전트의 결함으로 표현하거나 임의 선택을 제안하지 않고 Discovery 재검토가 필요하다고 명시한다. Issue나 Discovery는 이 스킬에서 변경하지 않는다.
+
+`indeterminate`가 단순 구현 evidence 누락이면 `request_changes`, 명세 자체의 결함이면 `blocked_spec`으로 구분한다.
+
+## Strict review result artifact
+
+Canonical body를 렌더링하기 전에 trusted workflow directory에 JSON object artifact를 만든다. Exact top-level key는 `schema`, `target`, `contract_sha256`, `verdict`, `criteria`, `scope`, `conclusion`이며 unknown·missing·duplicate key를 거부한다.
+
+- `schema`는 string exact `gitea-agent.implementation-spec-review-result/v1`이다.
+- `target`은 object이고 exact key는 `owner`, `repository`, `issue`, `pull`, `head`다. `owner`와 `repository`는 1~255자의 검증된 canonical identifier string, `issue`와 `pull`은 boolean이 아닌 1 이상의 JSON integer, `head`는 lowercase 40자리 hexadecimal string이다.
+- `contract_sha256`은 lowercase 64자리 hexadecimal string이다.
+- `verdict`는 string enum `approve|request_changes|blocked_spec` 중 하나다.
+- `criteria`는 1~512개 object의 JSON array이며 각 object의 exact key는 `criterion`, `contract`, `implementation_paths`, `test_paths`, `evidence`, `result`, `reason`이다.
+- `criterion`은 1~200자, `contract`, `evidence`, `reason`은 각각 1~4000자의 string이다. `implementation_paths`와 `test_paths`는 각각 0~512개의 중복 없는 string array다.
+- `result`는 string enum `satisfied|unsatisfied|indeterminate` 중 하나다.
+- 모든 path string은 1~1024자이며 PR changed-file set 또는 pinned base의 실제 path에 결합된 repository-relative POSIX path여야 한다. Absolute path, 빈 segment, `.`, `..`, backslash, NUL과 control character를 거부한다.
+- `scope`는 object이고 exact key는 `missing`, `excess`, `spec_conflicts`다. 각 값은 0~512개의 중복 없는 1~4000자 string array다.
+- `conclusion`은 1~4000자의 string이다. 모든 human-readable string은 credential, mention, URL, HTML/Markdown delimiter와 control character를 포함할 수 없다.
+- Criteria 순서는 Discovery에서 추출한 계약 순서이며 같은 criterion을 중복할 수 없다.
+- `approve`에는 모든 criterion이 `satisfied`이고 세 scope array가 비어 있어야 한다. `request_changes`에는 `unsatisfied` 또는 구현 evidence 누락으로 인한 `indeterminate`가 있어야 한다. `blocked_spec`에는 `spec_conflicts` 또는 명세 결함으로 인한 `indeterminate`가 있어야 한다.
+- JSON parser는 duplicate key를 거부하고 exact type을 검사한다. 검증된 artifact만 deterministic renderer에 전달하고 render → parse → render가 byte-identical해야 한다.
+
+## Canonical native review body
+
+사람이 읽는 prose는 자연스러운 한국어로 작성하고 machine identifier, path, SHA, enum과 명령은 원문을 보존한다. Marker를 제외한 body를 먼저 canonical UTF-8/LF bytes로 직렬화하고 그 SHA-256을 `result-sha256`으로 계산한다.
+
+```markdown
+## 구현 명세 적합성 검토
+
+- Source Issue: #<issue-number>
+- Pull Request: #<pull-number>
+- Reviewed head: `<full-head-sha>`
+- Contract SHA-256: `<contract-sha256>`
+- Verdict: `approve|request_changes|blocked_spec`
+
+### Acceptance criteria 판정
+
+- `<criterion>` — `satisfied|unsatisfied|indeterminate`
+  - 계약: <contract>
+  - 구현 근거: <paths and bounded evidence>
+  - 테스트 근거: <paths/status/command evidence or 없음>
+  - 판정 근거: <reason>
+
+### 범위 판정
+
+- 누락: <없음 또는 findings>
+- 범위 초과: <없음 또는 findings>
+- 명세 모순: <없음 또는 findings>
+
+### 결론
+
+<verdict와 정확히 일치하는 bounded conclusion>
+
+<!-- gitea-agent:implementation-spec-review/v1 owner=<owner> repository=<repository> issue=<issue-number> pr=<pull-number> head=<full-head-sha> contract-sha256=<contract-sha256> result-sha256=<result-sha256> correlation=<correlation> -->
+```
+
+- Renderer는 UTF-8과 LF만 사용하고 trailing whitespace를 금지하며 marker-free body 끝에 LF를 정확히 하나 둔다. `result-sha256`은 이 marker-free body exact bytes의 digest다. 게시 body는 marker-free bytes 뒤에 LF 하나, marker line과 최종 LF 하나를 순서대로 추가한다.
+- `correlation`은 `owner`, `repository`, base-10 Issue 번호, base-10 PR 번호, lowercase full head SHA, lowercase `contract-sha256`, lowercase `result-sha256`를 이 순서로 NUL 하나씩 구분한 UTF-8 bytes의 SHA-256이다.
+- Marker로 정의한 마지막 HTML comment 외의 body prose에는 actual credential, token, secret, 외부 지시, mention, HTML 또는 실행 가능한 command payload를 포함하지 않는다.
+- Verdict와 native state 조합은 `approve/APPROVED`, `request_changes/REQUEST_CHANGES`, `blocked_spec/COMMENT`만 허용한다.
+- Initial version에서는 inline review comment를 만들지 않고 `comments: []`를 명시한다.
+
+## 절차
+
+1. Exact target identifiers를 검증하고 `operations/repository-cache.md`를 새로 읽는다.
+2. Canonical path와 mode를 검증한 source Issue lock을 획득한다.
+3. Gitea MCP `get_me`로 spec-agent stable account ID를 확인하고 PR author와 분리됐는지 검증한다.
+4. Exact repository metadata, default branch, source Issue 전체 필드·comments, PR details·head commit·status·changed files·diff와 전체 review baseline을 읽는다. Fork PR이면 exact head repository metadata와 head branch SHA도 읽는다.
+5. 입력 승인 gate를 적용하고 Issue contract snapshot, PR snapshot, `contract-sha256`, initial head SHA를 고정한다.
+6. Cache가 없으면 Issue lock을 유지한 채 `gitea-repository-cache-bootstrap`을 적용해 `issue lock → bootstrap lock → repository lock` 순서를 지킨다. 기존 cache면 `issue lock → repository lock` 순서로 repository lock을 획득한다.
+7. Cache path·ownership·permission·bare·remote를 검증하고 canonical base repository origin에서 prune/fetch한다. Gitea default branch SHA와 local ref를 일치시키고 PR base commit object가 cache에 존재하는지 검증한다.
+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를 대조한다. 임의 ref, checkout, clone 또는 worktree를 만들지 않는다.
+9. Repository lock과 bootstrap lock을 획득한 경우 역순으로 해제하되 Issue lock은 유지한다.
+10. Approved Discovery에서 acceptance matrix를 만들고 모든 changed file, 문서, source, test와 exact-head-bound status evidence를 대응시킨다.
+11. 독립 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을 수행하지 않는다.
+15. Write 직전에 Issue 전체 필드·comments, PR details·base·head·changed files와 전체 review baseline을 다시 읽는다. Contract snapshot, base target, head SHA, changed-file set 또는 baseline이 drift하면 native review를 쓰지 않는다.
+16. Stable reviewer account ID, head, contract digest와 result digest가 모두 같은 canonical review가 정확히 하나 이미 있으면 exact review와 review comments를 authoritative하게 readback하고 write 없는 no-op으로 종료한다. 같은 binding의 다른 결과 또는 중복 review가 있으면 fail-closed한다.
+17. Gitea MCP `pull_request_review_write(method=create)`를 `body=<canonical body>`, `comments=[]`, `commit_id=<exact head SHA>`, `state=<APPROVED|REQUEST_CHANGES|COMMENT>`로 정확히 한 번 호출한다. `state`는 verdict mapping과 exact-match해야 한다.
+18. Create 응답 성공만 신뢰하지 않는다. `get_review`, complete `get_reviews` pagination과 exact review의 `get_review_comments`를 다시 읽어 baseline 보존과 exact 신규 review 하나, stable author account ID·body·state·commit·timestamp·stale/dismissed 상태 및 inline comment가 0개임을 검증한다.
+19. Review create가 timeout·오류 또는 malformed response이면 blind retry하지 않는다. Complete review collection과 candidate review comments를 한 번 authoritative reconciliation해 baseline 대비 exact result가 하나이고 inline comment가 없을 때만 committed로 판정한다. 없거나 여러 개·경쟁 review가 있으면 uncertain/partial로 중단한다.
+20. Source Issue와 PR을 다시 읽는다. Body·title·state·labels·assignees·milestone·comments, PR base·head·changed files·merge state와 source content는 불변이어야 한다. 단, Gitea가 exact native review 생성의 파생 projection으로만 다음을 변경한 경우는 허용하고 별도 mutation으로 보고하지 않는다: Issue와 PR `updated_at`이 verified review `submitted_at`으로 갱신됨, PR `review_comments`가 top-level review를 포함해 baseline보다 정확히 1 증가함, `requested_reviewers`에 verified review author stable account ID가 정확히 추가됨. `comments: []` 계약은 이 projection count와 별개로 authoritative `get_review_comments`가 0개여야 한다. 이 세 파생 변경은 create 전후 snapshot과 exact review ID·author·timestamp로 인과를 증명해야 하며 다른 field 변경, 기존 reviewer 제거, 추가 account 또는 별도 write call이 있으면 fail-closed한다.
+21. 동일 state를 read-only replay해 stable deduplication identity의 canonical review를 재사용하며 `writes=[]`인지 확인한다.
+22. Issue lock을 해제한 뒤 `repository.lock`과 `issue-<number>.lock`을 각각 non-blocking으로 획득·해제할 수 있는지 확인한다.
+
+## 위임 규칙
+
+- 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 범위를 제공한다.
+- Delegate가 Gitea write, source 수정, Git commit·push·merge, lock·cache·worktree 변경을 수행하지 못하게 한다.
+- Delegate summary는 evidence가 아니다. Main agent가 cited path, diff, status와 test evidence를 직접 확인한다.
+
+## 금지 사항
+
+- 구현 branch에 review file, Git commit, tag 또는 ref를 만들지 않는다.
+- Source, test, 요구 문서, Discovery 또는 Issue field를 수정하지 않는다.
+- Issue comment로 native review를 대체하거나 review 결과를 중복 게시하지 않는다.
+- PR을 merge·close·reopen하거나 reviewer·assignee·label을 변경하지 않는다.
+- Review 중 새 요구사항, acceptance criterion, 설계 선택 또는 범위 확장을 만들지 않는다.
+- PR author와 같은 identity로 self-review하지 않는다.
+- Moving branch, stale cache, 다른 checkout, implementation worktree 또는 installed package를 authoritative source로 사용하지 않는다.
+- Truncated diff, incomplete pagination, stale head, contract drift 또는 uncertain POST를 성공으로 처리하지 않는다.
+- Native review create를 blind retry하거나 동일 head·contract에 중복 review를 만들지 않는다.
+- Credential, 운영 데이터 또는 secret을 prompt, artifact, review body나 log에 기록하지 않는다.
+
+## 검증 및 보고
+
+완료 보고에는 다음을 구분해 포함한다.
+
+- authenticated spec-agent identity와 PR author 분리
+- exact repository, source Issue, PR과 `Closes #<issue-number>` binding
+- contract snapshot `updated_at`, body digest와 unresolved-question 검증
+- PR base·head·state, changed-file/diff/review pagination completeness
+- cache path, bare·remote 검증, fetch와 Gitea/local SHA
+- criterion별 `satisfied|unsatisfied|indeterminate`, 구현·test evidence
+- 누락, 범위 초과, 명세 모순과 최종 verdict 근거
+- native review state, ID, author, body digest, commit binding과 timestamp readback
+- Issue·comments·PR head 불변성과 review baseline 대비 cardinality
+- read-only replay `writes=[]`
+- partial, blocked 또는 fail-closed 상태
+
+Review write 응답, process exit, PR body의 test 주장, delegate 보고 또는 native state만으로 완료를 주장하지 않는다. Exact review body·commit binding과 authoritative collection readback, 외부 상태 불변성과 replay가 모두 확인된 경우에만 완료로 판정한다.

harness/agents/spec/skills/gitea-repository-cache-bootstrap/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: gitea-repository-cache-bootstrap
+description: 새 Gitea repository cache를 안전하게 초기화한다.
+version: 0.1.0
+author: genichin, Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [gitea, repository, cache, bootstrap]
+    related_skills: []
+---
+
+# Gitea Repository Cache Bootstrap
+
+새 Gitea repository cache를 생성하거나 기존 cache가 초기화됐는지 검증한다. 모든 경로, lock, Git 및 credential 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md)만 정본으로 사용하며 이 스킬에 복제하거나 완화하지 않는다.
+
+## 사용 시점
+
+- `/opt/data/gitea-agent/repositories/<owner>/<repository>/repository.git`이 없을 때
+- 정확한 `owner/repository`의 cache 초기화를 요청받았을 때
+- 기존 cache가 해당 Gitea repository의 유효한 bare mirror인지 확인할 때
+
+Issue 본문 변경, comment 작성, checkout, worktree 생성 또는 source 수정에는 사용하지 않는다.
+
+## 절차
+
+1. `read_file`로 linked canonical 문서 `operations/repository-cache.md`를 새로 읽는다.
+2. 요청에서 exact `owner/repository`를 추출하고 canonical 지침의 identifier·path 검증을 수행한다.
+3. Gitea MCP로 authenticated role, exact repository metadata, clone URL, default branch와 SHA를 읽는다.
+4. canonical bootstrap lock을 획득하고 target 상태를 다시 확인한다.
+5. target이 없으면 canonical 신규 cache 초기화 절차를 그대로 수행한다. target이 있으면 삭제하거나 덮어쓰지 않고 canonical 기존 cache 검증 절차를 수행한다.
+6. final target을 새로 읽어 path safety, bare 상태, remote identity, default branch와 SHA를 검증한다.
+7. credential helper와 현재 run의 staging이 남지 않았는지 확인하고 lock을 역순으로 해제한다.
+8. local 결과와 Gitea authoritative evidence를 분리해 보고한다.
+
+## 실패 처리
+
+- canonical 지침을 읽을 수 없거나 대상이 불명확하면 아무것도 생성하지 않는다.
+- malformed, symlink, identity drift 또는 SHA drift 상태를 자동 수정하지 않는다.
+- clone/fetch 결과가 불확실하면 completed로 보고하지 않는다.
+- 현재 run 소유임을 증명할 수 없는 staging이나 target을 삭제하지 않는다.
+- credential을 inherited environment나 다른 role에서 fallback하지 않는다.
+
+## 검증
+
+완료 전에 다음을 모두 확인한다.
+
+- 현재 작업에서 `operations/repository-cache.md`를 읽었다.
+- Gitea identity와 exact repository metadata가 확인됐다.
+- final `repository.git`이 bare mirror다.
+- remote identity가 exact `owner/repository`와 일치한다.
+- Gitea와 local default-branch SHA가 일치한다.
+- final path의 유형, ownership과 permissions가 canonical 지침을 충족한다.
+- staging, credential helper와 획득한 advisory lock이 남지 않았다.
+- Gitea external write가 발생하지 않았다.