[verified] docs: harden Gitea access and release contracts

harness/operations/repository-cache.md

@@ -1,19 +1,28 @@
 # Repository cache 운영 지침
 
-이 문서는 Gitea Agent harness가 사용하는 local repository cache의 canonical 운영 규칙이다. 모든 agent와 skill은 cache를 생성·갱신·검증할 때 이 문서를 읽고 따라야 하며 별도의 완화된 규칙을 만들지 않는다.
+이 문서는 Gitea Agent harness가 사용하는 local repository cache의 canonical 운영 규칙이다. 모든 agent와 skill은 cache를 생성·갱신·검증할 때 이 문서와 [Gitea authenticated access 운영 지침](gitea-access.md)을 읽고 따라야 하며 별도의 완화된 규칙을 만들지 않는다.
 
 ## 목적과 범위
 
 Repository cache는 Gitea repository의 Git 객체와 refs를 재사용하기 위한 bare mirror다. 문서 근거 조사와 Issue별 worktree 생성의 source로 사용할 수 있지만 그 자체는 checkout, 작업 공간 또는 외부 상태의 정본이 아니다.
 
-- Gitea MCP readback이 repository identity와 authoritative ref의 정본이다.
+- Canonical access 계약을 충족하는 authenticated Gitea API readback이 repository identity와 authoritative ref의 정본이다.
 - `repository.git`은 확인한 Gitea 상태와 일치할 때만 사용한다.
 - cache 생성과 갱신은 local filesystem 및 Git refs만 변경한다. Gitea에는 write하지 않는다.
 
+## Harness root 결정
+
+Repository cache 경로는 고정된 machine-local 절대경로나 현재 작업 directory에서 추측하지 않는다. Agent가 이번 작업에서 `read_file`로 실제 읽은 이 문서의 경로가 exact `<harness-root>/harness/operations/repository-cache.md` 형식인지 확인하고, 그 경로에서 `<harness-root>`를 계산한다. 따라서 repository 전체를 다른 위치에 설치해도 cache root는 항상 `<harness-root>/repositories`다.
+
+- 이 문서의 경로, `operations`, `harness`와 `<harness-root>`를 각각 `lstat`하고 symlink가 아닌지 확인한다.
+- 문서 경로가 위 구조와 exact-match하지 않거나 `<harness-root>`를 하나로 결정할 수 없으면 fail-closed한다.
+- `pwd`, shell 시작 directory, 사용자 home, 다른 checkout, 환경변수 또는 과거 session 값을 root 결정 근거로 사용하지 않는다.
+- Source checkout과 runtime cache가 같은 root 아래 있더라도 repository source로 혼동하지 않는다. Runtime cache는 `<harness-root>/repositories` 아래에서만 관리한다.
+
 ## 경로 구조
 
 ```text
-/opt/data/gitea-agent/repositories/
+<harness-root>/repositories/
 ├── .locks/
 │   └── <owner>/
 │       └── <repository>.bootstrap.lock
@@ -40,11 +49,13 @@ Repository cache는 Gitea repository의 Git 객체와 refs를 재사용하기
 
 1. `owner`와 `repository`는 요청에서 받은 값을 보존하되 각각 안전한 단일 경로 요소인지 검증한다.
 2. 빈 값, 경로 구분자, NUL, `.`과 `..` 또는 traversal을 허용하지 않는다.
-3. `/opt/data/gitea-agent`는 지정된 trusted harness root다. NFS mount root의 numeric owner가 실행 UID와 달라도 허용하지만 exact path가 directory이고 symlink가 아니며 world-writable이 아닌지 확인한다.
-4. trust boundary 아래 `repositories`, `.locks`, owner, repository와 `locks`는 생성 전후 `lstat`으로 검사한다. 모두 symlink가 아닌 directory, 실행 role 소유, mode `0700`이어야 한다.
-5. lock 파일과 임시 credential helper는 실행 role 소유와 mode `0600`을 요구한다.
-6. `worktrees`, `issue-<issue-number>`와 `checkout`은 symlink가 아닌 directory이고 실행 role 소유여야 한다. `worktrees`와 Issue directory는 mode `0700`, `state.json`은 mode `0600`이어야 하며 checkout과 그 상위 경로는 group 또는 world-writable이면 안 된다.
-7. 기존 path가 malformed 상태면 삭제, chmod, chown, reset 또는 덮어쓰기로 자동 복구하지 않고 fail-closed한다. 권한 변경은 운영자가 exact path와 mode를 명시적으로 승인한 경우에만 수행하고 즉시 재검증한다.
+3. 위 규칙으로 계산하고 검증한 `<harness-root>`만 trusted harness root로 사용한다. Exact path가 symlink가 아닌 directory이고 world-writable이 아닌지 확인한다. NFS mount root의 numeric owner가 실행 UID와 달라도 허용한다.
+4. 기존 `repositories`는 `lstat`으로 검사해 symlink가 아닌 directory, 실행 role 소유이며 world-writable이 아님을 확인한다. Group-writable이면 directory의 numeric GID가 현재 system에서 해석되고, 해당 GID를 primary group으로 쓰는 계정과 group member 목록을 합친 effective member가 실행 role 하나뿐임을 확인해야 한다. Group identity나 전체 membership을 확인할 수 없거나 다른 계정이 포함되면 fail-closed한다.
+5. 새 `repositories`를 만들 때는 실행 role 소유와 mode `0700`으로 생성한다. 기존 directory가 4번의 검증을 통과하면 mode `0700`, `0750`, `0755`, `0770` 또는 `0775`를 자동으로 chmod하지 않고 그대로 사용할 수 있다.
+6. Trust boundary 아래 `.locks`, owner, repository와 `locks`는 생성 전후 `lstat`으로 검사한다. 모두 symlink가 아닌 directory, 실행 role 소유, mode `0700`이어야 한다.
+7. Lock 파일과 임시 credential helper는 실행 role 소유와 mode `0600`을 요구한다.
+8. `worktrees`, `issue-<issue-number>`와 `checkout`은 symlink가 아닌 directory이고 실행 role 소유여야 한다. `worktrees`와 Issue directory는 mode `0700`, `state.json`은 mode `0600`이어야 하며 checkout과 그 상위 runtime 경로는 group 또는 world-writable이면 안 된다.
+9. 기존 path가 malformed 상태면 삭제, chmod, chown, reset 또는 덮어쓰기로 자동 복구하지 않고 fail-closed한다. 권한 변경은 운영자가 exact path와 mode를 명시적으로 승인한 경우에만 수행하고 즉시 재검증한다.
 
 ## Lock 규칙
 
@@ -60,7 +71,7 @@ Repository cache는 Gitea repository의 Git 객체와 refs를 재사용하기
 
 ## 신규 cache 초기화
 
-1. Gitea MCP `get_me`로 허용된 role identity를 확인한다.
+1. Authenticated Gitea API adapter로 허용된 role의 stable account identity를 확인한다. MCP면 `get_me`, 직접 REST면 `GET /api/v1/user`를 사용한다.
 2. exact `owner/repository` metadata, clone URL, default branch와 branch SHA를 Gitea에서 읽는다.
 3. bootstrap lock을 획득한 뒤 target을 다시 검사한다. 이미 유효한 cache가 있으면 새로 만들지 않고 기존 cache 검증 절차로 전환한다.
 4. trusted parent 아래 같은 filesystem에 run-unique sibling staging directory를 mode `0700`으로 만든다.
@@ -121,7 +132,7 @@ Repository cache는 Gitea repository의 Git 객체와 refs를 재사용하기
 Worktree를 신규 생성하거나 기존 worktree에서 구현을 재개하기 전에 다음을 모두 확인한다.
 
 1. exact `owner`, `repository`와 Issue 번호가 검증됐고 Issue lock을 획득했다.
-2. Gitea MCP로 authenticated role, exact repository metadata, Issue body, `updated_at`과 구현 승인 상태를 읽었다.
+2. Authenticated Gitea API adapter로 role identity, exact repository metadata, Issue body, `updated_at`과 구현 승인 상태를 읽었다.
 3. repository cache가 이 문서의 path, ownership, permission, bare, remote identity와 authoritative ref 검증을 통과했다.
 4. 구현에 사용할 exact base SHA와 그 출처를 결정했다. Discovery pinned revision과 현재 default branch SHA가 다르면 어느 한쪽을 자동 선택하지 않고 변경을 조사해 요구사항과 충돌하지 않는 base를 확정하거나 중단한다.
 5. `repository.git`에 exact base SHA의 commit object가 존재한다. 문자열 형식이나 object 존재만으로 Gitea 또는 승인된 Discovery에서 유래했다는 검증을 대체하지 않는다.
@@ -195,7 +206,7 @@ Dirty worktree, untracked 파일 또는 base 이후 commit은 진행 중 구현
 - worker에게 credential 값 또는 credential-bearing URL을 전달하지 않는다.
 - Git 인증이 필요하면 short-lived askpass 또는 동등한 child-process mechanism을 사용하고 종료 시 제거한다.
 - inherited credential, 다른 role의 credential 또는 interactive prompt로 fallback하지 않는다.
-- 인증에 실패하면 public clone이나 MCP content read를 initialized mirror의 증거로 대체하지 않고 중단한다.
+- 인증에 실패하면 public clone이나 unauthenticated API·content read를 initialized mirror의 증거로 대체하지 않고 중단한다.
 - Worktree source, state, Git config, reflog message, commit, patch, test artifact 또는 push refspec에 credential을 기록하지 않는다.
 
 ## Fail-closed 조건