--- name: gitea-issue-rework description: Gitea PR 검토 지적을 계약에 맞춰 재작업하고 검증한다. version: 0.2.12 author: genichin, Hermes Agent license: MIT platforms: [linux] metadata: hermes: tags: [gitea, implementation, rework, review, pull-request] related_skills: [gitea-issue-implementation] --- # Gitea Issue Rework `gitea-issue-implementation`으로 전달한 기존 Gitea PR에 대해 `gitea-spec-agent` 또는 승인된 `gitea-review-agent`가 남긴 검토 결과를 exact reviewed head와 승인된 Issue 계약에 결합해 재작업한다. 유효한 지적만 source·문서·test·evidence에 반영하고 같은 Issue 전용 branch에 non-force push한 뒤, exact final head에 결합된 bounded PR comment로 재검토 handoff를 게시한다. 새 요구사항을 만들거나 명세를 구현에 맞춰 완화하지 않으며 merge, Issue 변경과 review 작성은 수행하지 않는다. 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를 식별할 수 있는 요청에 사용한다. ```text / Issue # 구현 PR #의 검토 지적을 재작업하라 ``` 이 요청은 아래 작업만 승인한다. - 기존 canonical Issue worktree 검증과 재사용 - 승인된 계약 안에서 검토 지적을 해결하는 문서, source, test, 설정과 evidence 수정 - synthetic fixture와 test-only credential을 사용한 build, test, lint, 실제 runtime·browser 검증 - 기존 Issue 전용 branch 위의 non-amended commit 생성과 non-force push - 현재 PR 본문의 기존 의미와 `Closes #`를 보존하면서 재작업 요약과 최종 검증 결과를 갱신하는 작업 - 이 스킬의 canonical 형식과 deduplication 계약을 만족하는 재작업 결과 PR comment 하나의 생성 또는 기존 exact comment 재사용 다음 작업은 별도 요청이 없으면 승인되지 않는다. - 새 worktree나 대체 PR 생성, 다른 branch 또는 default branch로 push - force-push, rebase, amend, reset, clean, stash 또는 history rewrite - PR merge·close·reopen, native review·review reply·임의 comment 작성, reviewer 지정 또는 approval - Source Issue `#`의 body·comment collection·title·state·label·assignee·milestone 변경. Canonical PR comment는 exact Pull Request `#`의 top-level conversation에만 쓰며, provider가 이를 PR 자체의 underlying issue record `#` comment로 저장하는 projection은 허용한다. Source Issue record와 PR underlying issue record를 identifier·object kind·pull relation으로 구분할 수 없으면 게시하지 않는다. - 승인된 Discovery의 범위·결정·acceptance criterion 변경 - release, package 또는 deployment 게시 최초 구현, 독립 review, Discovery 변경 또는 이미 반영된 지적의 재검토에는 사용하지 않는다. ## 입력 승인 gate Repository file을 수정하기 전에 다음을 모두 검증한다. - `owner`, `repository`, Issue 번호와 PR 번호가 canonical identifier다. - Impl role의 authenticated stable account identity와 credential provenance를 확인했다. - PR은 open이고 source Issue와 exact `Closes #` 하나로 결합되며 PR author의 stable account ID가 현재 authenticated impl role의 stable account ID와 exact-match하는 기존 구현 PR이다. - PR base는 target repository의 default branch이고 head repository·branch·40자리 full SHA를 식별할 수 있다. - Current Issue body는 유효한 `gitea-agent:discovery-draft/v2` 계약이고 미해결 질문이 없으며 body SHA-256을 계산할 수 있다. - 재작업 대상 native review의 ID, author stable account ID, state, body, reviewed commit SHA, stale·dismissed 여부와 inline comments를 complete pagination으로 읽었다. - Review author가 허용된 spec 또는 code-review role이고 impl role과 다른 identity다. - `REQUEST_CHANGES` 또는 명시적인 actionable finding이 있으며 각 finding의 계약 근거와 대상 경로를 판독할 수 있다. - Review가 참조한 contract digest가 있으면 current Issue body digest와 exact-match한다. - Reviewed head가 current PR head와 exact-match한다. 다르면 current head에 결합된 더 최신 authoritative review를 사용하고, 없으면 이전 지적을 새 head에 임의 적용하지 않고 중단한다. - Changed-file, review, review-comment와 commit pagination이 완전하고 diff가 truncated·ambiguous하지 않다. - Canonical Issue worktree와 PR head branch를 현재 실행이 안전하게 재사용할 수 있다. `COMMENT` review도 exact head에 결합된 actionable code finding이면 다른 finding과 같은 matrix로 분류할 수 있다. 그러나 `COMMENT`의 `blocked_spec`, 계약 모순, 선택되지 않은 설계 선택 또는 source reality와 계약 충돌은 구현 재작업으로 해결하지 않는다. Discovery 재검토가 필요하다고 보고하고 source를 수정하지 않는다. `APPROVED` review만 존재하거나 actionable finding이 모두 최신 head에서 해소된 경우 write 없는 no-op으로 종료한다. ## Snapshot과 finding matrix 첫 write 전에 다음 immutable snapshot을 보존한다. - Issue title, body, state, `updated_at`, labels, assignees, milestone, 전체 comments와 body SHA-256 - PR title, body, state, `updated_at`, base·head repository와 branch, base·head SHA, author, changed files, commits, status, workflow run, PR top-level comment collection의 exact cardinality와 provider가 노출하는 comment-count field baseline - 전체 native review baseline과 대상 review의 ID, author, state, body digest, reviewed head, submitted time, stale·dismissed 상태와 inline comments - Worktree state identity, base SHA, current HEAD, detached·locked 상태, staged·unstaged·untracked file과 미완료 Git operation 기존 canonical requirement revision을 갱신하거나 기존 계약 보존이 승인 조건이면 pinned source revision 또는 직전 승인 revision의 모든 requirement·acceptance criterion·상태 불변조건을 의미 단위로 추출해 다음 Contract Preservation Inventory를 같은 snapshot에 고정한다. ID 변경만으로 보존을 판정하지 않는다. ```text baseline_revision: path: baseline_id: <기존 requirement 또는 AC ID> semantic_key: meaning: <정상·실패·경계·불변조건의 bounded 설명> reviewed_ids: [...] reviewed_status: preserved | intentionally_changed | missing | ambiguous planned_ids: [<재작업 후 대응 ID>...] planned_status: preserved | intentionally_changed | missing | ambiguous authorization: Issue contract citation authorizing intentional change, or none evidence_paths: [...] verification: ``` Baseline 항목은 중복 없이 정확히 한 번 나타나야 한다. `intentionally_changed`에는 승인된 Issue 근거가 필요하다. `reviewed_status`의 `missing`은 finding matrix에 포함하고 `ambiguous`는 계약 판단 불가로 중단한다. Repository 첫 write 전 계획 기준 `planned_status`가 `missing=0`, `ambiguous=0`이어야 한다. Contract Preservation Inventory를 delegate할 때는 immutable pre-write snapshot에 대해 완료·회수한 뒤에만 mutating worker를 시작하며, 편집과 병렬 실행해 중간 상태를 판정하지 않는다. 모든 finding을 다음 matrix의 정확히 한 항목으로 분류한다. ```text finding: / reviewed_head: contract: classification: valid_fix | evidence_gap | reviewer_misunderstanding | blocked_spec implementation_paths: [...] test_paths: [...] verification: <실행할 command/runtime/browser evidence> result: pending | resolved | unresolved reason: ``` - `valid_fix`: 승인 계약을 위반한 source·문서·설정·test 결함이다. - `evidence_gap`: 구현 적합성은 확인 가능하지만 exact-head-bound 실행·runtime·browser·CI evidence가 부족하다. - `reviewer_misunderstanding`: 지적이 승인 계약 밖의 새 요구사항이거나 authoritative tree와 맞지 않는다. 이를 만족시키려고 범위를 확장하지 않고 근거와 함께 unresolved로 보고한다. - `blocked_spec`: 명세 모순이나 새 결정이 필요하다. 모든 repository write를 중단한다. 완료 조건: 모든 review finding과 unsatisfied·indeterminate criterion이 matrix에 정확히 한 번 나타나고, `valid_fix`와 `evidence_gap`마다 변경 또는 검증 경로가 있으며, 이미 satisfied인 계약을 약화하는 항목이 없다. Contract Preservation Inventory가 필요한 경우 baseline 전체가 대응되고 `missing=0`, `ambiguous=0`이다. ## Canonical 재작업 결과 comment 재작업 branch를 전달한 뒤 reviewer가 새 head를 자동으로 재검토할 수 있도록 exact PR의 top-level conversation에 comment 하나를 게시한다. Adapter target은 object kind가 pull request이고 index가 exact ``인 record여야 한다. Provider가 PR comment를 underlying issue comment로 저장하면 exact comment endpoint target의 issue index가 ``이고 fresh PR metadata가 그 record를 같은 pull request로 식별함을 증명해야 한다. Comment object가 target kind를 반복하지 않는 API에서는 검증된 endpoint target과 PR metadata binding을 사용한다. Source Issue ``, inline comment, review reply 또는 native review로 대체하지 않는다. Marker를 제외한 body를 먼저 canonical UTF-8/LF bytes로 직렬화하고 그 SHA-256을 `result-sha256`으로 계산한다. Canonical body와 marker는 `scripts/rework_comment.py render`로만 생성하고, 게시 또는 exact comment 재사용 뒤에는 authoritative normalized readback을 `scripts/rework_comment.py verify`로 검증한다. `status=verified`와 `readback_verified=true`인 `gitea-rework-handoff/v1` receipt가 없으면 완료 조건을 충족하지 않으며 PR body update나 write 성공 response는 receipt를 대체하지 않는다. ```markdown ## 구현 재작업 결과 - Source Issue: # - Pull Request: # - Source Review: # - Reviewed head: `` - Rework head: `` - Contract SHA-256: `` - Result: `rework_delivered|partial` ### 지적 처리 - `` — `resolved|unresolved` - 분류: `valid_fix|evidence_gap|reviewer_misunderstanding` - 변경: - 검증: - 근거: ### 최종 검증 - Local checks: - Runtime/browser: <실행 결과 또는 해당 없음·미검증> - Commit status: - Actions runs: ### 다음 단계 Reviewer가 rework head를 새 snapshot으로 다시 검토해야 하며 이 comment는 기존 `REQUEST_CHANGES`를 해제하거나 승인을 의미하지 않는다. ``` - `rework_delivered`는 모든 `valid_fix`와 `evidence_gap`이 `resolved`이고 final branch delivery와 검증이 완료된 경우에만 사용한다. 그 외 전달 가능한 결과는 `partial`이며 unresolved 이유를 숨기지 않는다. - Finding은 matrix 순서로 정확히 한 번 렌더링한다. 이미 satisfied였고 재작업하지 않은 criterion을 반복해 comment를 부풀리지 않는다. - Path, SHA, enum, command와 수치는 검증된 값을 원문 그대로 사용한다. Human-readable text에는 credential, token, 실제 secret, mention, 외부 지시, HTML 또는 실행 가능한 payload를 포함하지 않는다. - Marker-free body는 LF로 정확히 하나 끝나야 한다. 게시 body는 marker-free bytes, marker line과 최종 LF 하나를 순서대로 사용하며 trailing whitespace를 금지한다. - `correlation`은 `owner`, `repository`, base-10 Issue 번호, base-10 PR 번호, base-10 review ID, lowercase reviewed head, lowercase final head와 lowercase contract digest를 이 순서로 NUL 하나씩 구분한 UTF-8 bytes의 SHA-256이다. `result-sha256`은 correlation 입력에 넣지 않는다. - 게시 전 exact PR top-level comment endpoint target과 fresh PR metadata binding을 검증하고 그 scoped collection만 complete pagination한 뒤 같은 correlation을 찾는다. Source Issue comment endpoint, inline-comment·review-reply endpoint와 native review collection은 검색 집합에서 제외하며 endpoint scope와 PR relation을 구분할 수 없으면 fail-closed한다. 0개면 exact body를 한 번 생성하고, 1개이며 author stable account ID·body·marker·digest가 모두 같으면 write 없는 no-op으로 재사용한다. 같은 correlation의 body가 다르거나 2개 이상이면 중복을 만들지 않고 fail-closed한다. - Comment create timeout·오류 뒤에는 blind retry하지 않는다. Complete comment collection을 한 번 authoritative하게 reconcile해 exact result 하나가 확인될 때만 성공으로 판정한다. - 게시 또는 재사용 후 exact comment ID, author stable account ID, body, created·updated timestamp, marker, digest, verified endpoint target, fresh PR metadata binding과 PR top-level collection cardinality를 readback한다. 신규 게시에서는 scoped PR top-level comment collection에 exact comment 하나만 추가되어야 한다. Provider의 aggregate comment-count field는 fresh top-level·review·inline comment cardinality로 설명 가능해야 하며 설명할 수 없으면 fail-closed한다. 해당 comment timestamp에 인과가 결합된 PR `updated_at` 변경만 허용한다. Source Issue ``는 body digest·title·state·labels·assignees·milestone·comment collection이 불변이어야 한다. `Closes #` 같은 provider relation 때문에 Source Issue `updated_at`만 변경되면 그 시각이 이번 PR comment 생성과 인과적으로 결합된 경우에만 허용한다. Existing exact comment 재사용에서는 PR top-level collection cardinality, PR·underlying issue와 Source Issue field가 모두 불변이어야 한다. 기존 review collection 또는 그 밖의 PR field 변경은 허용하지 않는다. 완료 조건: exact final head와 finding matrix에 결합된 canonical comment가 impl role author로 정확히 하나 존재하고 authoritative readback을 통과한다. ## 절차 ### Evidence manifest automation 모든 baseline, 통합·precommit 및 readback 검증은 `scripts/evidence_manifest.py`와 `templates/evidence-plan.json`을 사용해 exact argv, exit code, 제한된 output, 허용된 환경, source revision, 파일 hash와 표준 JSON-pointer claims를 기록한다. 명령은 argv 배열만 허용하고 명시된 최소 child-environment allowlist에서 실행하며 output 상한을 넘는 process는 중단한다. Secret·header·private-key·password 값이나 plan 금지 패턴이 발견되면 redaction하지 않고 fail-closed한다. `run`은 baseline부터 최종 precommit까지 사용하고, `validate`는 plan과 manifest를 제외한 clean tree에서 PR claim 생성 전에 실행한다. `validate`는 source ancestry와 hash를 다시 검증하며 evidence-only descendant에서는 기록된 hash path가 source blob과 동일해야 한다. 수동으로 매칭되지 않는 PR 성공·검증 주장을 만들지 않는다. Comment publish 전 remote immutable artifact의 digest를 authoritative readback으로 비교한다. ### 1. Target, identity와 review 고정 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를 그대로 보존한다. 5. Finding matrix를 만들고 `blocked_spec` 또는 판정 불가능한 finding이 있으면 수정 전에 중단한다. 완료 조건: exact review와 reviewed head, current PR head, Issue contract digest와 finding matrix가 동일 snapshot에 결합돼 있다. ### 2. Cache와 기존 worktree 검증 1. `read_file`로 `operations/repository-cache.md`를 새로 읽는다. 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. 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 검증이 모두 끝난 뒤 `release_repository` request를 보내고 일반 편집·test·commit 동안 Issue lease만 유지한다. 7. 다른 checkout, 임시 clone 또는 경쟁 worktree를 만들지 않는다. 완료 조건: 기존 worktree가 exact owner, repository, Issue, impl role, PR branch와 reviewed head에 결합되고 보존할 모든 기존 상태가 기록돼 있다. ### 3. 재작업 계획과 baseline 1. 각 `valid_fix`와 `evidence_gap`을 승인 계약의 acceptance criterion에 역추적한다. 2. 변경 allowlist를 source, 문서, 설정, test와 evidence path로 만든다. 불변성 또는 evidence 재사용 검증에는 계약을 실제로 소유하는 exact path·제한된 glob만 별도 기록하며 package 전체처럼 넓은 경로를 근거 없이 사용하지 않는다. Review body의 path를 존재 검증 없이 신뢰하지 않는다. 3. Repository의 canonical 문서 README·TEMPLATE, build·test·lint 명령과 변경 대상 파일을 다시 읽는다. 4. 현재 reviewed head에서 관련 test와 review가 요구한 runtime check를 baseline으로 실행하고 command, exit code, output, environment와 HEAD를 기록한다. 5. Framework·runtime·protocol capability가 불명확하면 production edit 전에 최소 spike로 검증한다. 6. Review가 실제 browser 동작을 요구하면 framework test client나 protocol client로 대체하지 않는다. 사용할 수 있으면 Playwright MCP `mcp__playwright__browser_*`로 실제 Chromium 흐름과 browser storage·cookie·navigation을 검증하고, 사용할 수 없으면 해당 criterion을 unresolved로 유지한다. 완료 조건: 각 remediation item에 exact path, 실패 또는 부족한 baseline evidence와 완료를 증명할 검증 방법이 연결돼 있다. ### 4. Test-first 수정 1. `valid_fix`마다 결함을 재현하는 가장 작은 regression test를 먼저 추가하거나 기존 test가 의도한 이유로 실패함을 확인한다. - Test file과 test function 이름은 추적 번호가 아니라 안정적인 기능·동작·불변조건을 표현한다. Issue, PR, review, comment 번호나 일시적인 finding ID를 이름에 넣지 않는다. 추적성은 finding matrix, commit, PR comment와 evidence metadata에 기록한다. 기존에 이미 존재하는 번호 기반 이름은 해당 재작업에서 별도 rename 범위를 승인받지 않았다면 유지한다. - 동시성·event-loop finding은 wall-clock 의존을 최소화한 deterministic unit test와 실제 delay를 활성화한 짧은 runtime probe를 모두 실행해, 지연 semantics 유지와 무관한 coroutine·health 요청의 응답성을 각각 검증한다. - Streaming request-body 상한 finding은 `Content-Length`를 신뢰하지 않고 실제 streamed bytes로 exact limit 허용, limit+1 거부, 누락·부정확한 `Content-Length`, 초과 뒤 `receive` 미호출을 검증한다. Upstream이 이미 전달한 단일 대형 chunk의 allocation은 애플리케이션이 막을 수 없다는 잔여 경계를 기록한다. 2. Source를 최소 변경해 test를 통과시키고 이미 satisfied인 criterion과 제외 범위를 보존한다. 3. `evidence_gap`은 production code를 불필요하게 바꾸지 않고 누락된 unit, integration, runtime, browser 또는 provenance evidence를 보강한다. 4. 보안 finding은 정상 경로뿐 아니라 fail-closed, no-call·no-write, 경계 시간, rotation 양방향, fresh session, logout 후 재접속과 credential 비노출을 해당 계약 범위에서 검증한다. 5. 문서 finding은 기존 canonical requirement ID와 revision history를 유지하고 요구사항, interface, project structure, runtime flow, deployment와 test를 일관되게 갱신한다. Review를 맞추기 위해 별도 요구사항 ID를 만들지 않는다. 6. 실제 credential, 운영 데이터 또는 민감 token을 fixture, evidence, log, screenshot, URL이나 repository file에 기록하지 않는다. 7. 각 item을 수정할 때 focused test를 실행하고 matrix의 `result`와 evidence를 갱신한다. 완료 조건: 모든 `valid_fix`가 재현 test와 수정 후 통과 evidence를 가지며, `evidence_gap`은 요구된 실제 검증 수준으로 채워졌거나 unresolved 이유가 명시돼 있다. ### 5. 통합 검증과 독립 검토 1. Repository가 선언한 formatter, lint, type check, build, targeted, integration과 relevant full suite를 실행한다. 2. Runtime·protocol·browser criterion은 가능한 가장 실제에 가까운 경로로 실행한다. 하위 수준 대체 evidence를 동등하다고 주장하지 않는다. 재작업 diff가 문서 파일에만 한정되고 기존 browser evidence가 결합된 source, test와 evidence path가 reviewed head부터 final head까지 byte-identical이며 ancestry를 검증한 경우에만 browser를 다시 실행하지 않고 기존 evidence를 재사용할 수 있다. 이때 비교한 exact path 집합과 양 head의 blob OID 또는 digest를 검증 기록과 결과 comment에 남긴다. 변경 경로가 겹치거나 동일성을 증명할 수 없으면 재사용하지 않는다. 3. Base-to-worktree와 reviewed-head-to-worktree diff를 모두 읽고 모든 changed file을 finding matrix와 acceptance matrix에 대응한다. 4. 범위 밖 refactor, debug artifact, generated drift, credential, 운영 데이터, test-only bypass와 예상하지 못한 삭제를 제거한다. 5. 독립 검토를 요청하기 전에 모든 actionable finding을 하나의 통합 adversarial suite로 실행한다. 각 finding은 실제 public response shape와 모든 직접 소비 경로를 포함해야 한다. 최소 검증 항목은 최초 실행과 idempotent replay의 응답 동등성, top-level/nested 필드 일치, 재귀적 민감정보 redaction, missing/initialized DB의 no-write, public positional signature, 동시성 및 실패 envelope다. 이 suite가 통과하지 않으면 독립 검토를 시작하지 않는다. 독립 검토는 새 결함을 처음 찾는 단계가 아니라 exact tree의 확인 단계다. 6. Security-sensitive 변경은 `delegate_task`로 bounded reviewer에게 exact worktree, reviewed head, contract subset, finding matrix와 file allowlist를 제공해 독립 검토한다. Gitea write, Git cleanup, commit과 push는 금지한다. 7. Delegate finding을 main agent가 직접 재현하고 유효한 문제만 수정한 뒤 영향을 받은 focused test와 relevant full suite를 다시 실행한다. 완료 조건: 모든 modified file이 approved finding 또는 필수 supporting change로 설명되고 unresolved finding과 검증 한계가 분리돼 있다. ### 6. Drift 확인과 commit 1. Issue, comments, PR, commits, changed files, branch SHA와 전체 reviews를 다시 읽는다. 2. Issue body digest·`updated_at`, PR base·head, 대상 review binding, review baseline 또는 default branch가 snapshot에서 material하게 drift하면 새 상태를 자동 채택하지 않고 중단한다. 3. Worktree의 staged·unstaged·untracked state와 미완료 Git operation을 확인한다. 4. Contract Preservation Inventory가 필요한 경우 final tree에 다시 대응해 baseline 항목 수와 실제 상태를 검증하고 `missing=0`, `ambiguous=0`이 아니면 stage하거나 commit하지 않는다. 5. Exact allowlist만 stage하고 staged diff를 다시 읽는다. 6. Repository convention에 맞는 새 non-amended rework commit을 생성한다. Review별 traceability가 필요하면 commit message나 검증 기록에 PR과 review ID를 포함하되 review body를 그대로 복제하지 않는다. 7. Commit 후 clean HEAD에서 최종 formatter, test와 필요한 runtime·browser 검증을 다시 실행한다. 이 뒤 repository file을 바꾸면 영향을 받은 검증을 다시 실행한다. 8. 최종 검증 기록은 exact HEAD 또는 검증한 source tree, command, exit code, pass·skip·fail 수치, 환경, relevant output과 reviewer가 접근 가능한 evidence location을 포함하며, PR body·결과 comment의 각 실행 주장과 수치는 해당 location에 일대일 대응시킨다. Hermes 내부 tool transcript, delegate 자기보고, 삭제 예정 임시 파일, reviewer가 접근할 수 없는 local path와 요약 수치만 있는 기록은 evidence로 인정하지 않고 `evidence_gap` 또는 `partial`로 유지한다. Tracked evidence가 final HEAD 자체를 포함할 수 없어 evidence-only descendant가 생기면 검증한 commit과 final head의 ancestry 및 검증 대상 path가 불변임을 명시하고 숨기지 않는다. 완료 조건: final local HEAD, clean state, finding별 해결 evidence와 단일 검증 기록이 일치하며, 필요한 Contract Preservation Inventory는 `missing=0`, `ambiguous=0`이다. ### 7. 기존 PR branch 전달 1. Write 직전에 remote branch와 PR head가 snapshot의 reviewed head와 여전히 exact-match하는지 확인한다. 2. 첫 delivery push 전에 승인된 noninteractive credential capability를 preflight하고 필요한 temporary askpass helper를 제한된 권한으로 준비한다. Credential은 출력하지 않고 주입하며 interactive prompt를 비활성화하고 push 시도 뒤 성공·실패와 무관하게 helper를 확정적으로 제거한다. 그 후 canonical mirror remote를 변경하지 않고 explicit repository URL과 refspec으로 기존 Issue 전용 branch에 fast-forward non-force push한다. Named mirror remote를 사용해야 하면 `operations/repository-cache.md`에 따라 해당 push 호출에서만 `remote..mirror=false`를 적용한다. 3. Push 결과만 신뢰하지 않고 remote branch SHA와 PR head SHA가 final local HEAD와 exact-match하는지 readback한다. 4. PR body 갱신이 필요한 경우 write 직전에 PR 전체 필드, review·comment·commit collection cardinality와 authenticated impl identity를 다시 읽는다. Current body의 `Closes #`와 기존 구현 내용을 보존하고 재작업 review ID·reviewed head·finding별 조치·최종 검증과 unresolved limitation만 반영한 exact body payload를 명시해 한 번만 호출한다. 성공 응답만 신뢰하지 않고 fresh PR과 관련 collection을 읽어 PR author stable account ID, exact body payload, `updated_at`, base·head·commit/ref, state·draft·merge 상태, labels·assignees·reviewer와 collection cardinality를 baseline과 비교한다. Exact body와 provider가 해당 body update로 파생한 `updated_at` 외의 변경은 승인되지 않았으며 인과를 증명할 수 없으면 partial로 중단한다. 5. PR changed files, commits, state, merge 상태, statuses와 workflow runs를 다시 읽는다. Local test, commit status와 Actions run을 별도 사실로 기록한다. 6. Finding matrix와 최종 검증 기록을 bounded JSON input으로 만들고 `scripts/rework_comment.py render --input --comment --expected `를 실행해 canonical 재작업 결과 comment, marker-free digest와 correlation을 생성·검증한다. Comment body와 marker를 수동 조립하지 않는다. 7. Exact PR top-level comment endpoint target과 fresh PR metadata binding을 검증해 Source Issue comments, inline comments, review replies와 native reviews에서 분리하고 scoped collection을 complete pagination한 뒤 canonical deduplication 규칙을 적용한다. Existing exact comment가 없으면 exact PR conversation에 body를 한 번 게시하고, 있으면 write 없이 재사용한다. 8. Exact comment와 scoped complete collection을 fresh normalized JSON으로 readback한 뒤 `scripts/rework_comment.py verify --expected --pr-readback --comments-readback --identity-readback --action --baseline-count --output `를 실행한다. Receipt의 comment ID, impl author stable account ID, body, timestamp, final head, digest, correlation과 cardinality가 검증돼야 하며, 신규 게시로 허용된 PR-underlying-issue projection 외의 PR field, Source Issue field와 기존 review collection에 변경이 없어야 한다. 9. Native review를 작성·dismiss·reply하거나 새 review를 요청하지 않는다. 기존 `REQUEST_CHANGES`는 reviewer가 새 head를 재검토하기 전까지 자동 해소된 것으로 주장하지 않는다. 10. Push, PR body 또는 comment write가 timeout·오류이면 blind retry하지 않고 branch, PR과 complete comment collection을 authoritative하게 reconcile한다. Exact write가 반영됐음을 증명할 수 없으면 partial 상태로 중단한다. 완료 조건: 같은 PR의 remote head가 final local HEAD와 일치하고 canonical 재작업 결과 comment가 정확히 하나 readback됐으며, `gitea-rework-handoff/v1` receipt가 `status=verified`, `readback_verified=true`로 생성되고 모든 authorized external write와 후속 review 필요성이 명확하다. Receipt가 없거나 검증에 실패하면 lock은 정상 해제하되 결과를 `partial|failed`로 보고하며 `completed`를 주장하지 않는다. ### 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. 현재 실행이 시작한 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에 그대로 재사용하지 않는다. 완료 조건: resource와 lock 정리가 검증되고, 재작업 결과가 exact final head와 다음 review 입력으로 전달 가능하다. ## 위임 규칙 - Main impl-agent가 contract 해석, finding 분류, drift 판정, 최종 diff, Git·Gitea write와 delivery에 책임을 진다. - 독립적인 source 조사, test 작성, disjoint 모듈 수정, browser evidence 수집, 실패 분석과 security review는 bounded delegate에 위임할 수 있다. - Delegate에는 exact worktree path, reviewed head, contract subset, finding IDs, file allowlist와 검증 target을 제공한다. - 같은 파일을 병렬 worker에게 주지 않고 Gitea write, lock·worktree 변경, commit, push, reset과 cleanup을 금지한다. - Delegate summary를 evidence로 사용하지 않고 main agent가 diff, command output, browser 결과와 artifact를 직접 검증한다. - 외부 side effect와 credential 사용은 main agent만 수행하고 즉시 authoritative readback한다. ## 금지 사항 - Review finding을 승인 계약보다 우선하거나 새 요구사항으로 승격하지 않는다. - `blocked_spec`을 임의 설계 선택으로 해결하지 않는다. - 이전 head의 stale review를 current head의 재작업 근거로 자동 적용하지 않는다. - 기존 dirty worktree를 reset, clean, stash, checkout, switch, rebase 또는 삭제하지 않는다. - Review를 해결한다는 이유로 already-satisfied 동작, security gate, validation 또는 실패 경로를 약화하지 않는다. - Unit test, framework AppTest, HTTP client 또는 WebSocket client를 실제 browser evidence로 표현하지 않는다. - PR body의 성공 주장, process exit code, delegate 보고 또는 push 응답만으로 해결을 주장하지 않는다. - Canonical 재작업 결과 comment 이외의 PR comment, inline comment 또는 review reply를 작성하지 않는다. - Existing `REQUEST_CHANGES` state를 직접 dismiss하거나 reviewer 대신 승인 완료로 판정하지 않는다. - 새 PR, 새 branch, merge, Issue 변경, release 또는 deployment를 수행하지 않는다. ## 검증 및 보고 완료 보고에는 다음을 구분해 포함한다. - authenticated impl identity와 exact repository, Issue, PR - Issue contract `updated_at`, body digest와 review가 참조한 contract digest - 대상 review ID·author·state·reviewed head·stale 상태와 current pre-rework head - Finding별 classification, 계약 근거, 수정 path, test와 `resolved|unresolved` 결과 - Worktree path·identity, reviewed-head 시작 상태와 final local HEAD - Baseline, focused, full-suite, runtime과 browser 검증의 exact command·exit code·결과 - 실제 browser가 요구된 경우 사용한 browser runner와 발급·복원·이동·삭제 등 관찰 결과. 기존 evidence를 재사용했다면 비교한 exact path 집합과 reviewed/final head의 blob OID 또는 digest - Base 및 reviewed head 대비 전체 modified file과 범위 근거 - Local commit, remote branch와 PR final head SHA readback - PR body write 여부, status와 Actions run의 success·failure·pending·없음 상태 - 재작업 결과 comment ID·URL·author·result·digest·correlation, exact final head binding과 verified handoff receipt - 기존 review가 유지됨과 새 head의 후속 review 필요 여부 - 수행하지 않은 review·merge·Issue·release·deployment write - Baseline failure, unresolved finding, specification blocker, unavailable evidence와 partial write - 임시 resource 정리와 lock 해제 확인 모든 finding이 해결되고 검증된 final commit과 canonical 결과 comment가 기존 PR에 전달돼도 후속 reviewer가 새 head를 검토하기 전에는 `승인 완료`라고 보고하지 않는다. Final head와 exact comment readback, 전체 diff, 실제 검증 evidence와 resource·lock 정리가 일치할 때만 `재작업 전달 및 comment handoff 완료`로 판정한다.