docs(review): clarify bounded J4 finalization procedure

2026-10-09 02:12:45 +00:00
parent 137827ead9
commit d92811ec1c
2 changed files with 4 additions and 2 deletions
@@ -71,7 +71,9 @@ Bootstrap 이후 code review는 canonical [Repository cache 운영 지침](../..
 2. Canonical path·권한·state identity·common Git directory·detached/locked registration을 검증한다. HEAD는 현재 PR head와 같고 미완료 Git operation과 tracked 변경이 없어야 한다.
 3. Untracked 파일, dependency 환경과 설정이 검증을 오염시키지 않는지 확인한다. 설명할 수 없는 상태는 reset·clean·stash·checkout으로 복구하지 않고 중단한다.
 4. Source·test·Git refs·state는 수정하지 않는다. 테스트 출력·fixture·DB는 격리된 임시 경로를 사용하고 운영 데이터·credential을 사용하지 않는다. 파일 수정이나 위험한 외부 쓰기가 필요한 명령은 실행하지 않는다.
-5. 실행 전후 HEAD와 tracked/untracked 상태를 비교한다. 현재 실행이 만든 자원만 정리하고, 모든 종료 경로에서 canonical broker cleanup(보유한 `release_repository` → `release` → tracked broker wait/reap → `probe` `free=true`)을 검증한다.
+5. 실행 전후 HEAD와 tracked/untracked 상태를 비교한다. 정상 종료 시 source에 영향을 줄 수 있는 실행 작업의 실제 종료를 확인하고, 유효한 Issue lease 아래 필요한 최종 HEAD·Git 상태·source digest 검증을 끝내어 기존 결과 artifact에 근거를 보존한 뒤 canonical broker cleanup(보유한 `release_repository` → `release` → tracked broker wait/reap → Issue `probe` `free=true`)을 수행한다. 최종 검증과 Issue `release`를 독립 병렬 작업으로 배치하지 않는다. 검증 실패·취소에서도 현재 실행이 만든 자원만 정리하고 cleanup을 시도하되 검증 성공이나 workflow 완료로 기록하지 않는다.
+
+Cleanup이 미확인이라는 이유로 완료한 검토·전체 테스트·Native POST를 자동 반복하지 않는다. 추가 자동 재시도 루프나 heartbeat를 도입하지 않고 기존 명령 timeout과 tracked process의 유한한 wait를 사용한다. Cleanup이 끝나지 않으면 기존 결과 artifact에 마지막 확인 단계와 미확인 원인을 남기고 workflow를 `partial`로 보고한다. 재개 시 이미 확인된 `release`를 다시 강제하지 않고, 보존된 근거와 현재 프로세스 상태를 대조하여 미완료 cleanup 확인만 수행한다. Issue probe `busy`만으로 현재 실행의 lock 누수를 단정하지 않으며, 현행 `free=true` 완료 조건은 유지한다. 정상 해제 뒤 terminal handle 상태가 `released`로 남아 있어야 한다는 조건을 추가하지 않는다. 재개가 source 검증이나 게시 작업으로 확장되면 기존 유효 lease·head·계약 검사를 다시 적용한다.

 안전한 대여가 불가능하면 CI·기존 근거를 사용하고 직접 실행 불가 사유를 보고한다. 필수 검증 근거가 부족하면 승인하지 않는다. 독립성은 reviewer의 판단과 직접 확인에 있으며 별도 checkout 자체가 필수는 아니다.

@@ -39,7 +39,7 @@ Keep `gitea-access.md` and `repository-cache.md` authoritative. Before calling `
 1. Admit the canonical, existing role-owned repository cache and impl-created, registered detached/locked worktree. Complete the independent code review and collect evidence on the exact source head.
 2. Authenticate **one** transport from the current role's `$HERMES_HOME/.env` `GITEA_TOKEN`, or an explicitly authorized role-scoped external secret source. No ambient-token fallback, cross-profile credentials, credential-bearing Git URLs or anonymous downgrade is allowed.
 3. Validate the exact fixed origin `https://gitea.jsfamily.quest/api/v1` and `GET /user` account ID/login. The transport must verify TLS, reject redirects, bound network timeouts and **not retry mutation requests**. The bridge's provenance labels are assertions supplied by this already-validated caller, not a mechanism to load or certify an arbitrary client.
-4. Use the common broker Issue lease throughout publication/readback. Pass a live monotonic deadline, not an old PID/`ready.json` flag. `BrokerIssueLease` checks broker status and canonical worktree invariants; renew before expiry. `HeldIssueLease` is compatibility-only and may be used only by an already-admitted legacy caller, never to create a second lock protocol. The caller must run canonical release/wait/reap/probe cleanup. A custom supervisor lease must implement the same invariants: `check(plan)` returns `None` only on success and otherwise raises; boolean/dict success flags are unsupported.
+4. Use the common broker Issue lease throughout publication/readback. Pass a live monotonic deadline, not an old PID/`ready.json` flag. `BrokerIssueLease` checks broker status and canonical worktree invariants; renew before expiry. `HeldIssueLease` is compatibility-only and may be used only by an already-admitted legacy caller, never to create a second lock protocol. The caller must run canonical release/wait/reap/probe cleanup. A custom supervisor lease must implement the same invariants: `check(plan)` returns `None` only on success and otherwise raises; boolean/dict success flags are unsupported. Finalization follows the [review execution procedure](../SKILL.md#실행-검증과-기존-워크트리-사용): complete required final source verification under the held lease and preserve its evidence before releasing. `verified.json` proves publication verification, not workflow cleanup. Retain the same publication journal and existing result artifacts when cleanup is incomplete; report workflow partial and reconcile only unfinished cleanup checks, without replaying a full review, suite or POST. Keep the common Issue-resource `free=true` completion requirement; do not add a released-only terminal-handle gate or a new automatic retry/heartbeat loop.
 5. Put the journal outside every source checkout in a trusted artifact parent. Use the **same journal for every retry/resume of this plan**, not a new directory after a timeout. The adapter creates mode 0700 directories and 0600 atomic/fsynced artifacts, rejects symlinks/hardlinks/foreign or unsafe modes, and holds a separate nonblocking journal mutex. Redact secrets before constructing plans/artifacts; do not log request headers, raw transport exceptions or token values. Journals contain complete source snapshots and must remain private.

 The current helper is strict about worktree child directories: group/world-writable checkout paths are rejected. Do not change a real worktree's permissions to force publication; stop and reconcile an admission/publisher compatibility conflict. The legacy compatibility bridge is Linux-only: it validates an already-admitted broker-held whole-file lease represented by an exclusive `FLOCK` owned by this process in `/proc/self/fdinfo`, and never acquires or reacquires that resource. New callers use `BrokerIssueLease` and the broker public request API. It uses a root-owned, non-group/world-writable `/usr/bin/git` with a fixed minimal environment, not the caller's `PATH`.