Add shared managed lock broker

2026-10-07 02:23:39 +00:00
parent 18676070b2
commit 470c7fb09b
16 changed files with 1583 additions and 120 deletions
@@ -1,7 +1,7 @@
 ---
 name: gitea-issue-implementation
 description: 승인된 Gitea Issue를 구현·검증하고 Gitea PR로 전달한다.
-version: 0.4.5
+version: 0.4.6
 author: genichin, Hermes Agent
 license: MIT
 platforms: [linux]
@@ -15,6 +15,11 @@ metadata:

 승인된 Gitea Discovery와 pinned repository revision을 근거로 Issue별 persistent worktree에서 요구 문서, source와 test를 구현하고 검증한 뒤 Issue 전용 branch와 Gitea PR로 전달한다. Gitea 인증과 readback은 [Gitea authenticated access 운영 지침](../../../../operations/gitea-access.md), repository cache와 worktree 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md), 문서 형식은 `docs/` 아래 각 문서 유형의 README와 TEMPLATE만 정본으로 사용한다. Exact Issue 구현 요청은 승인된 범위의 commit, 일반 push와 PR 생성을 승인하며, 열린 PR의 authoritative readback까지가 이 스킬의 기본 완료 경계다. PR 전달을 별도 승인 단계로 미루지 않는다. 다만 merge, force-push, Issue close, release 또는 deployment는 승인하지 않는다.

+
+## Managed-lock broker gate
+
+Issue workflow는 bootstrap 이후 반드시 [Repository cache 운영 지침](../../../../operations/repository-cache.md)의 하나의 role-neutral managed-lock broker를 사용한다. `serve`를 tracked background process로 시작하고 ready JSON을 기다리며, checkout 밖 role-owned mode `0700` runtime directory와 run-unique handle/socket을 미리 만든다. Client는 raw token을 inspect/log하지 않으며 public `request` API가 token을 캡슐화한다. Repository lock은 같은 handle의 `acquire_repository`/`release_repository` request로만 중첩하고, TTL 전에 `renew`한다. 정상·오류·cancel 모두 `release_repository`(보유 시) → `release` → broker wait/reap → `probe`의 `free=true` 확인 순서를 완료하기 전에는 완료·로그·보고하지 않는다. Raw `flock ... sleep`과 lock-file unlink는 금지한다.
+
 ## 사용 시점

 다음과 같이 exact repository와 Issue를 지정해 구현을 요청받았을 때 사용한다.
@@ -66,19 +71,19 @@ Issue body와 `updated_at`을 immutable approval snapshot으로 보존한다. bo

 모든 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 workflow 전체에서 broker가 관리하는 exact Issue lease를 유지한다.
+- Cache 초기화·fetch·ref 검증과 worktree 등록 변경에는 같은 handle로 `acquire_repository` request를 보내 repository lease를 추가한다.
+- 일반 편집과 test에는 broker Issue lease만 유지한다.
 - 다른 Issue worktree나 다른 checkout을 읽기·수정·정리하지 않는다.
- lock을 획득할 수 없거나 현재 실행이 lock 순서를 증명할 수 없으면 fail-closed한다.
- 종료, 오류와 중단 경로에서 현재 실행이 획득한 lock만 역순으로 해제한다.
+- broker request가 실패하거나 현재 실행이 broker lease 순서를 증명할 수 없으면 fail-closed한다.
+- 종료, 오류와 중단 경로에서 현재 실행이 보유한 repository lease를 `release_repository`, Issue lease를 `release` request로 해제한다.

 ## 절차

 ### 1. Target과 identity 고정

 1. 요청에서 exact `owner`, `repository`와 Issue 번호를 추출하고 각각 canonical identifier 규칙으로 검증한다.
-2. Issue lock을 획득한다.
+2. Broker `serve`가 관리하는 Issue lease를 public `request` API의 `status`/ready 응답으로 확인한다.
 3. Canonical authenticated Gitea API adapter로 현재 impl role의 stable account identity를 확인한다.
 4. 같은 adapter로 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으로 기록한다.
@@ -100,7 +105,7 @@ Issue body와 `updated_at`을 immutable approval snapshot으로 보존한다. bo

 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 일치를 검증한다.
+3. Issue lease를 유지한 채 같은 broker handle로 `acquire_repository` request를 보내 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로 사용한다.
@@ -116,7 +121,7 @@ Issue body와 `updated_at`을 immutable approval snapshot으로 보존한다. bo
 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은 유지한다.
+7. `release_repository` request를 보내고 Issue lease는 유지한다.

 완료 조건: exact worktree path, base SHA, current HEAD, detached·locked 상태와 approval snapshot binding이 canonical 검증을 통과한다.

@@ -175,7 +180,7 @@ Discovery가 `신규 작성` 또는 `수정`으로 판정한 문서만 작성한
 ### 9. Drift 확인, commit과 PR 전달 — 필수 완료 gate

 1. Gitea Issue와 comments를 다시 읽어 approval snapshot의 body, `updated_at`과 comment baseline drift를 확인한다.
-2. Repository lock 아래 origin을 다시 fetch하고 Gitea default branch SHA와 local ref를 확인한다.
+2. Broker Issue lease를 유지한 채 같은 handle에 `acquire_repository`를 request하고, 그 repository lease 아래 origin을 다시 fetch해 Gitea default branch SHA와 local ref를 확인한 뒤 `release_repository`를 request한다.
 3. Default branch가 base 이후 전진했으면 자동 merge, rebase 또는 history rewrite하지 않는다. 새 변경이 구현과 충돌하지 않는지 판정할 수 없으면 delivery-ready로 보고하지 않는다.
 4. Worktree의 base SHA, final HEAD, staged·unstaged·untracked 상태, 미완료 Git operation과 test 결과를 기록한다.
 5. Remote branch 이름은 repository convention이 있으면 이를 따르고, 없으면 `gitea-agent/issue-<number>-<short-slug>`처럼 deterministic Issue 전용 이름을 사용한다. Gitea와 remote에서 동일 이름의 branch와 열린 PR을 먼저 조회해 중복 생성하지 않는다. 이 이름으로 canonical mirror의 `refs/heads/*`에 local branch를 만들거나 Issue worktree를 attach하지 않는다.
@@ -190,7 +195,7 @@ Discovery가 `신규 작성` 또는 `수정`으로 판정한 문서만 작성한
 14. Gitea에서 PR details, base branch, head repository·branch·SHA, state, changed files와 commit을 다시 읽는다. 최종 remote head SHA가 최종 local commit SHA와 일치할 때만 전달 완료로 판정한다.
 15. Gitea Actions 또는 commit status가 제공되면 최종 head의 success, failed, pending, run 없음 또는 조회 불가 상태를 읽고 그대로 보고한다.
 16. PR 생성 또는 후속 push가 부분 실패하면 blind retry하거나 중복 PR을 만들지 않는다. 이미 생성된 fork·branch·PR과 local commit의 exact 상태 및 안전한 복구 지점을 보고한다.
-17. 성공·실패와 관계없이 현재 실행이 만든 임시 server, fixture workspace와 credential helper를 정리하고 부재를 확인한 뒤 현재 실행이 획득한 lock을 해제한다. Persistent Issue worktree는 별도 제거 승인이 없으면 보존한다.
+17. 성공·실패와 관계없이 현재 실행이 만든 임시 server, fixture workspace와 credential helper를 정리하고 부재를 확인한 뒤 보유한 repository lease에 `release_repository`, Issue lease에 `release` request를 보낸다. Persistent Issue worktree는 별도 제거 승인이 없으면 보존한다.

 완료 조건: Issue와 source drift, final worktree 상태와 실행 결과가 fresh readback으로 확인되고, Issue worktree가 final commit의 detached HEAD로 남아 있으며, 열린 Gitea PR의 base·head와 remote head SHA가 검증된 최종 local commit에 exact-match하고, mirror fetch가 구현 branch checkout 충돌 없이 성공하며, 임시 resource와 lock 정리가 검증됐다. 열린 PR이 없으면 명시적인 local-only 제한이나 외부 permission blocker가 기록된 경우를 제외하고 스킬은 미완료다.

@@ -1,7 +1,7 @@
 ---
 name: gitea-issue-rework
 description: Gitea PR 검토 지적을 계약에 맞춰 재작업하고 검증한다.
-version: 0.2.10
+version: 0.2.11
 author: genichin, Hermes Agent
 license: MIT
 platforms: [linux]
@@ -17,6 +17,11 @@ metadata:

 Gitea 인증과 authoritative readback은 [Gitea authenticated access 운영 지침](../../../../operations/gitea-access.md), cache·lock·worktree 규칙은 [Repository cache 운영 지침](../../../../operations/repository-cache.md), 문서 형식은 `docs/` 아래 각 문서 유형의 README와 TEMPLATE만 정본으로 사용한다.

+
+## Managed-lock broker gate
+
+Bootstrap 이후 이 Issue 재작업도 canonical [Repository cache 운영 지침](../../../../operations/repository-cache.md)의 공통 managed-lock broker 하나만 사용한다. `serve`는 checkout 밖 pre-created mode `0700` role-owned runtime directory, unique handle/socket, tracked background process와 ready JSON을 요구한다. 같은 handle로만 public `request` API의 `acquire_repository`/`release_repository`를 요청하고 TTL 전에 `renew`한다. Client는 raw token을 inspect/log하지 않으며 broker request API가 token을 캡슐화한다. 정상·오류·cancel cleanup은 보유한 repository lease release, Issue `release`, broker wait/reap, `probe`의 `free=true` 확인까지 동일하며 그 전에는 completed/log/report를 주장하지 않는다. Raw `flock ... sleep`, lock-file unlink와 client-side lock holder는 금지한다.
+
 ## 사용 시점

 다음처럼 exact repository, source Issue, 기존 구현 PR과 재작업할 review를 식별할 수 있는 요청에 사용한다.
@@ -169,7 +174,7 @@ Reviewer가 rework head를 새 snapshot으로 다시 검토해야 하며 이 com

 ### 1. Target, identity와 review 고정

-1. Exact target identifier를 검증하고 Issue lock을 획득한다.
+1. Exact target identifier를 검증하고 broker `serve`의 ready 응답과 public `request` API로 Issue lease를 확인한다.
 2. Canonical authenticated Gitea adapter로 impl role identity, repository, Issue, PR, commits, changed files, statuses, workflow runs, 전체 reviews와 review comments를 읽는다.
 3. 입력 승인 gate를 적용하고 Issue·PR·review snapshot을 저장한다.
 4. Review marker에 head, contract digest, result digest 또는 correlation이 있으면 형식과 authoritative 값의 일치를 검증한다. Marker가 없는 code review는 review ID·author·commit binding과 finding body를 그대로 보존한다.
@@ -180,11 +185,11 @@ Reviewer가 rework head를 새 snapshot으로 다시 검토해야 하며 이 com
 ### 2. Cache와 기존 worktree 검증

 1. `read_file`로 `operations/repository-cache.md`를 새로 읽는다.
-2. Issue lock 아래 canonical 순서로 repository lock을 획득하고 cache path·ownership·permission·bare·remote를 검증한 뒤 origin에서 prune/fetch한다.
+2. Issue lease를 유지한 채 같은 broker handle로 `acquire_repository` request를 보내 cache path·ownership·permission·bare·remote를 검증한 뒤 origin에서 prune/fetch한다.
 3. Gitea default branch와 local ref, PR base·head object 및 remote head branch SHA를 대조한다. Fork PR이면 target cache에 head object가 있다고 가정하지 않고 authoritative head repository와 branch를 별도로 검증한다.
-4. Issue lock과 repository lock을 모두 유지한 상태에서 기존 Issue worktree의 state identity, Git registration, common directory, detached·locked 상태, current HEAD, index, tracked·untracked state와 미완료 Git operation을 검증한다.
+4. Broker Issue lease와 repository lease를 모두 유지한 상태에서 기존 Issue worktree의 state identity, Git registration, common directory, detached·locked 상태, current HEAD, index, tracked·untracked state와 미완료 Git operation을 검증한다.
 5. Worktree HEAD와 PR head SHA가 다르거나 dirty state가 snapshot으로 설명되지 않거나 다른 실행의 lock·Git operation이 있으면 reset·checkout·clean으로 복구하지 않고 중단한다.
-6. Worktree admission 검증이 모두 끝난 뒤 repository lock을 해제하고 일반 편집·test·commit 동안 Issue lock만 유지한다.
+6. Worktree admission 검증이 모두 끝난 뒤 `release_repository` request를 보내고 일반 편집·test·commit 동안 Issue lease만 유지한다.
 7. 다른 checkout, 임시 clone 또는 경쟁 worktree를 만들지 않는다.

 완료 조건: 기존 worktree가 exact owner, repository, Issue, impl role, PR branch와 reviewed head에 결합되고 보존할 모든 기존 상태가 기록돼 있다.
@@ -259,7 +264,7 @@ Reviewer가 rework head를 새 snapshot으로 다시 검토해야 하며 이 com
 ### 8. 종료와 다음 review handoff

 1. 임시 검증 자원을 정리하기 전에 relevant output을 redaction하고 exact HEAD·command·exit code·환경과 결합해 reviewer-accessible evidence location에 저장한 뒤 그 내용을 readback한다. 그 후 임시 server, probe script·raw output, browser context, fixture workspace와 credential helper를 정리하고 부재를 확인한다.
-2. 현재 실행이 시작한 lock holder는 lock FD를 상속한 자식 process까지 함께 종료한다. Shell PID 종료만으로 해제를 판정하지 않으며, 현재 실행이 획득한 lock을 역순으로 해제한 뒤 repository lock과 Issue lock을 각각 non-blocking으로 실제 재획득·해제한 경우에만 cleanup 완료로 판정한다.
+2. 현재 실행이 시작한 tracked broker process와 그 자식 process를 cleanup 대상으로 관리한다. Shell PID 종료만으로 해제를 판정하지 않으며, 보유한 repository lease를 `release_repository`하고 Issue lease를 `release`한 뒤 broker를 wait/reap하고 `probe`에서 `free=true`를 확인한 경우에만 cleanup 완료로 판정한다.
 3. Finding matrix, final diff, 검증 기록, remote head와 CI/status를 다시 대조한다.
 4. 모든 item이 `resolved`여도 reviewer의 새 head 검토 전에는 구현 승인 완료가 아니라 `재작업 전달 및 comment handoff 완료, 재검토 대기`로 보고한다.
 5. 후속 review가 새 head에 `REQUEST_CHANGES`를 남기면 그 review를 새 immutable snapshot으로 하는 별도 재작업 iteration을 시작한다. 이전 review snapshot이나 matrix를 새 head에 그대로 재사용하지 않는다.