genichin/gitea-agent

Fork 0

Files

T

gitea-spec-agent 9367d5a3a1 [verified] Gate adoption of delegated evidence

2026-10-11 06:08:32 +00:00

34 KiB

Raw Blame History

name, description, version, author, license, platforms, metadata

name

description

version

author

license

platforms

metadata

gitea-issue-implementation

승인된 Gitea Issue를 구현·검증하고 Gitea PR로 전달한다.

0.4.9

genichin, Hermes Agent

MIT

linux

hermes

Gitea Issue Implementation

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

Test inventory source-binding gate

Baseline/current inventory를 생성·전달·채택할 때 check-tests 이전에 harness/lib/test_inventory_binding.py를 실행한다. Inventory의 자기 선언을 신뢰하지 않고 독립적으로 고정한 revision과 stage를 expected 입력으로 제공한다. Exact Git blob의 파일 존재·SHA-256 및 collection scope 결속을 공통 source-binding 정본에 따라 확인하고, 통과한 ID/source가 이후 구조 guard 입력과 같은지도 대조한다. 불일치 증빙을 채택하거나 현재 collection을 baseline으로 재명명하지 않는다. PASS가 named test의 존재·collection 실행·의미 보존을 인증하지는 않으며 main의 실제 실행 provenance 검토와 기존 revision evidence 영향 평가를 유지한다. 이 gate는 제품 실행·별도 checkout 권한이나 자동 제품 변경 요청을 추가하지 않는다.

Delegation evidence acceptance gate

위임 결과 채택 이전에 harness/lib/delegation_evidence.py를 공통 증빙 채택 정본에 따라 실행한다. main이 독립적으로 고정한 context에 source/bundle digest, 허용 작업, 검증 항목과 독립 실행 catalog를 넣으며 worker 자기 선언으로 context를 만들지 않는다. Source line/named test anchor와 실제 보존된 회귀 테스트·RED/GREEN 기록을 대조하고, bundle 추출 범위 밖 부재 주장은 authoritative Git 조회 없이 채택하지 않는다. Import·환경 오류를 RED로 취급하거나 확인되지 않은 위임 주장을 최종 판정·delivery·publication 근거로 옮기지 않는다. Static-only worker가 기존 독립 실행 근거를 인용하는 것과 직접 실행하는 것을 구분한다. BLOCK/입력 거부이면 해당 증빙 채택을 중단하고 main이 실제 기록과 의미를 재검증한다. Gate는 sandbox, 실행 인증 또는 assertion 의미 판정기가 아니며 기존 compare-source/check-tests와 role의 제품 실행 제한을 대체하지 않는다.

Managed-lock broker gate

Issue workflow는 bootstrap 이후 반드시 Repository cache 운영 지침의 하나의 role-neutral managed-lock broker를 사용한다. serve에 canonical Issue identity, role, workflow run-id와 TTL을 전달해 broker-generated runtime을 만들고, ready JSON의 handle/socket 경로만 사용한다. 경로는 <issue>/runtime/<workflow-run-id>/broker.handle과 broker.sock이며 verification stage run-id와 독립적이다. Runtime 생성은 approval이나 worktree admission을 대신하지 않는다. Cache bootstrap 이후 broker가 Issue lock 아래 runtime을 준비하고, ready 이후 각 workflow의 진입 검증·승인 조건을 확인한다. 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를 지정해 구현을 요청받았을 때 사용한다.

<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

위 commit·push·PR 전달은 선택적 후속 작업이 아니라 이 스킬의 기본 완료 조건이다. 사용자가 같은 요청에서 명시적으로 local-only, commit 금지, push 금지 또는 PR 생성 금지라고 제한한 경우에만 해당 write를 생략하며, 그때는 이 스킬을 완료로 보고하지 않고 제한된 local 결과로 보고한다.

다음 작업은 요청 문구에 별도로 명시되지 않으면 승인되지 않는다.

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에는 사용하지 않는다. 전달한 PR에 spec 또는 code review가 REQUEST_CHANGES나 actionable finding을 남긴 뒤의 수정은 이 최초 구현 절차를 반복하지 않고 gitea-issue-rework로 handoff한다.

정본과 승인 gate

구현을 시작하려면 현재 Issue body가 다음을 모두 충족해야 한다.

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

절차

1. Target과 identity 고정

요청에서 exact owner, repository와 Issue 번호를 추출하고 각각 canonical identifier 규칙으로 검증한다.
Broker serve가 관리하는 Issue lease를 public request API의 status/ready 응답으로 확인한다.
Canonical authenticated Gitea API adapter로 현재 impl role의 stable account identity를 확인한다.
같은 adapter로 exact repository metadata, default branch와 SHA, Issue 전체 필드와 전체 comment baseline을 읽는다.
title, body, state, labels, assignees, milestone, updated_at, comment cardinality와 body digest를 immutable approval snapshot으로 기록한다.

완료 조건: authenticated identity, exact target과 재현 가능한 approval snapshot이 모두 존재한다.

2. Discovery와 산출물 계약 추출

승인 gate로 current body를 검증한다.
포함 범위, 제외 범위, 제약 조건과 확정된 결정을 중복 없이 추출한다.
각 문서의 조치, exact path와 필수 내용을 추출한다. 영향 없음인 문서를 생성하지 않는다.
사용자 관찰 가능 동작, 실패 동작, 보안 불변조건, 호환성 조건과 외부 write 경계를 acceptance matrix로 만든다.
각 acceptance criterion에 예정된 문서, source 위치와 검증 test를 연결한다. 연결할 수 없는 criterion이 있으면 구현 전에 중단한다.
기존 canonical requirement revision을 갱신하는 경우 pinned source revision 또는 직전 승인 revision의 모든 requirement·acceptance criterion·상태 불변조건을 의미 단위로 추출해 Contract Preservation Inventory를 만든다. 각 항목에 baseline_revision, path, baseline_id, ID와 독립적인 semantic_key, meaning, planned_ids, planned_status: preserved | intentionally_changed | missing | ambiguous, authorization, evidence_paths, verification을 기록한다. intentionally_changed에는 승인된 Issue 근거가 필요하며 ID 변경만으로 의미 보존을 판정하지 않는다.

완료 조건: 모든 확정된 결정과 산출물이 acceptance matrix의 한 항목 이상에 대응하고, 제외 범위가 구현 항목에 포함되지 않는다. 기존 requirement revision이면 baseline 전체가 inventory에 중복 없이 정확히 한 번 대응하고 repository 첫 write 전 계획 기준 missing=0, ambiguous=0이다.

3. Cache 검증과 base 결정

operations/repository-cache.md를 새로 읽는다.
Canonical 절차로 cache를 초기화하거나 기존 cache를 검증한다. malformed cache를 삭제, reset, chmod, chown 또는 다른 repository로 교체하지 않는다.
Issue lease를 유지한 채 같은 broker handle로 acquire_repository request를 보내 exact origin에서 prune/fetch하고 Gitea default branch SHA와 local ref 일치를 검증한다.
Discovery pinned SHA가 cache에 존재하는 commit object이고 Issue가 주장한 revision과 exact-match하는지 확인한다.
Pinned SHA와 current default branch SHA가 같으면 이를 base로 확정한다.
두 SHA가 다르면 pinned revision부터 current default branch까지의 commit과 변경 파일을 조사한다. 변경이 Discovery 근거, 요구 문서 ID·경로, 대상 API, test contract 또는 acceptance criteria를 무효화하지 않는다는 근거가 있을 때만 current default branch SHA를 base로 사용한다.
변경이 material하거나 요구사항과 충돌하거나 안전하게 판정할 수 없으면 worktree를 만들거나 수정하지 않고 renewed Discovery가 필요하다고 보고한다.

완료 조건: Gitea와 local에서 확인된 full base SHA, 선택 근거와 pinned-to-base 차이 판정이 기록돼 있다.

4. Worktree 생성 또는 재사용

Approval snapshot이 아직 current Issue와 exact-match하는지 다시 읽는다.
operations/repository-cache.md의 admission gate를 그대로 적용한다.
신규 worktree는 canonical path에서 exact base SHA의 detached HEAD로 생성하고 Issue 용도로 lock한다.
gitea-agent.worktree/v1 state를 canonical 방식으로 게시한다.
기존 worktree는 state identity, Git registration, common directory, detached·locked 상태, base ancestry, dirty 상태와 미완료 Git operation을 모두 검증한 뒤 재사용한다.
기존 worktree의 파일, untracked state 또는 commit을 reset, clean, rebase, checkout, switch 또는 삭제로 자동 복구하지 않는다.
release_repository request를 보내고 Issue lease는 유지한다.

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

5. Repository baseline 조사

search_files, read_file과 worktree를 대상으로 한 read-only terminal Git 명령으로 tree, build 설정, test runner, formatter, lint와 기존 문서 구조를 조사한다.
Discovery가 언급한 모든 source와 test 경로를 실제 base에서 읽는다. 읽지 않은 파일을 근거로 구현을 설계하지 않는다.
Repository가 선언한 canonical install과 test 명령을 찾는다. 임의의 전역 package 설치나 운영 credential을 사용하지 않는다.
관련 기존 test를 수정 전 실행하고 exit code와 실패 내용을 보존한다.
Baseline 실패가 변경 대상과 관련되거나 새 구현의 판정을 방해하면 수정하지 않고 blocker로 보고한다. 명백히 무관한 기존 실패라면 범위와 evidence를 기록하고 영향받는 test를 별도로 판정한다.
Acceptance criterion이 framework·runtime·protocol의 특정 capability에 의존하고 base에서 지원 여부가 불명확하면 production 변경 전에 최소 spike로 실제 API와 lifecycle을 검증한다. 검증할 수 없거나 요구 동작을 지원하지 않으면 설계를 추측해 구현하지 않는다.

완료 조건: 변경 대상의 현재 동작, dependency direction, test command와 baseline 결과가 실제 output으로 확인됐고, 구현을 좌우하는 capability 불확실성이 해소됐다.

6. 요구 문서 작성

Discovery가 신규 작성 또는 수정으로 판정한 문서만 작성한다.

Target repository의 기존 canonical 문서와 requirement ID를 먼저 조사해 신규 문서와 기존 revision 갱신을 구분한다. 요구사항명세서는 read_file로 harness의 요구사항 작성 방법과 요구사항 템플릿을 새로 읽고 Discovery가 지정한 target repository의 exact ID·경로로 작성한다.
데이터 모델은 영향이 있을 때만 harness의 데이터 모델 작성 방법과 데이터 모델 템플릿을 적용한다.
인터페이스 계약은 영향이 있을 때 harness의 인터페이스 계약 작성 방법과 인터페이스 계약 템플릿을 적용한다.
프로젝트 구조는 영향이 있을 때 harness의 프로젝트 구조 작성 방법과 프로젝트 구조 템플릿을 적용한다.
런타임 흐름은 영향이 있을 때 harness의 런타임 흐름 작성 방법과 런타임 흐름 템플릿을 적용한다.
Requirement frontmatter는 canonical gitea-agent.requirement/v1 계약을 만족하고 status를 approved로 기록한다. 구현 PR이 아직 없으면 미정을 유지하고 번호를 추측하지 않는다.
모든 placeholder, 작성 안내 문구, 실제 credential과 확인되지 않은 경로를 제거한다.
기존 requirement revision이면 작성 결과에 Contract Preservation Inventory를 다시 대응하고 missing=0, ambiguous=0을 검증한다. 충족하지 못하면 문서 작성 완료로 판정하지 않는다.

완료 조건: Discovery의 문서 영향 판정과 생성·수정된 문서 집합이 정확히 일치하고 각 문서가 해당 README와 TEMPLATE 검증을 통과하며, 필요한 Contract Preservation Inventory는 missing=0, ambiguous=0이다.

7. Test-first 구현

공통 workflow guard 계약을 baseline 조사·첫 편집·독립 검토·결과 채택 단계에 적용한다. 첫 편집 전에 테스트 ID/skip/expected-failure와 영향을 받는 기존 API·CLI·상태·cleanup 의미를 기록하고 check-tests --input JSON 및 check-contracts --input JSON으로 검증한다. 읽기 전용 worker 시작 전에 python3 <harness-root>/harness/lib/workflow_guard.py snapshot --repo-root ROOT --paths-json INPUT --output SNAPSHOT으로 immutable protected scope를 고정하고, 결과 채택 전에 compare-source --repo-root ROOT --before SNAPSHOT --paths-json INPUT을 실행한다. 쓰기 worker의 승인된 편집은 실제 diff로 검토하며 최종 독립 검토 중에는 보호 범위 mutator를 실행하지 않는다. 기록은 제품 checkout 밖 정본 verification run에 보존한다. 변경된 테스트의 의미 보존과 named finding의 실제 RED/GREEN 원인은 main agent가 확인한다. 필요한 gate·근거가 미해결이면 완료로 판정하지 않는다.

Acceptance matrix에서 변경 전 실패해야 하는 정상, 실패, 경계와 보안 test를 먼저 추가한다.
- Test file과 test function 이름은 추적 번호가 아니라 안정적인 기능·동작·불변조건을 표현한다. Issue, PR, review, comment 번호나 일시적인 finding ID를 이름에 넣지 않는다. 추적성은 acceptance matrix, commit, PR과 evidence metadata에 기록한다.
새 test가 의도한 이유로 실패하는지 실행해 확인한다. 환경 오류나 잘못된 fixture 실패를 RED evidence로 사용하지 않는다.
기존 architecture와 dependency direction을 유지하는 최소 source 변경으로 test를 통과시킨다.
실패 경로가 외부 상태를 변경하지 않는지 검증한다.
실제 운영 데이터, password, token 또는 credential을 test와 fixture에 사용하지 않는다.
Timing, concurrency 또는 retry 조건은 clock·sleep 의존성을 주입하거나 통제 가능한 seam으로 unit test하되, Discovery가 실제 elapsed-time 보장을 요구하면 실제 통합 경로 test도 유지한다.
관련 test를 작은 단위로 반복한 뒤 전체 관련 suite를 실행한다.

완료 조건: 각 acceptance criterion에 실제로 실행된 test 또는 판정 가능한 문서·정적 검증 evidence가 연결돼 있다.

8. 통합 검증과 독립 검토

Repository가 요구하는 formatter, lint, type check, build와 test suite를 실제 실행한다.
Base-to-worktree diff를 읽고 모든 변경 파일을 acceptance matrix와 대응한다.
범위 밖 변경, debug artifact, generated drift, credential material, query parameter secret, test-only bypass와 운영 데이터가 없는지 검사한다.
새 dependency나 새 API가 있다면 필요성, 선언된 version 범위에서의 API 지원, lockfile과 모든 runtime·deployment 설치 경로의 일치를 검증한다.
설정 예시에는 secret 이름과 용도만 기록하고 실제 값을 넣지 않는다.
인증, credential, cookie, HTTP origin·scheme, proxy trust 또는 권한 경계를 변경하면 delegate_task로 bounded security reviewer를 사용하고 scheme·host·port, trusted proxy, fail-closed ordering과 secret 노출을 명시적으로 검토한다. 그 외에는 독립 검토가 유용할 때 reviewer를 사용한다. Reviewer에게 exact worktree path, base SHA, Issue snapshot, acceptance matrix와 검증 명령을 전달하고 Gitea write, Git cleanup, commit과 push를 금지한다.
Main agent가 reviewer 지적을 직접 재현하고 유효한 문제만 수정한 뒤 영향을 받은 검증을 다시 실행한다.
실제 runtime·protocol 동작이 acceptance criterion이면 가능한 가장 실제에 가까운 경로로 검증한다. 필요한 tool이 없으면 하위 수준 검증으로 대체하되 동등하다고 주장하지 않고 미검증 범위를 기록한다. Timeout이나 비결정적 실패가 발생했거나 timeout 값을 변경했다면 focused test를 fresh process에서 반복한 뒤 관련 suite와 전체 suite를 다시 실행한다.

완료 조건: 모든 modified file이 승인된 산출물로 설명되고, 실행한 quality gate와 unresolved finding이 명확하다.

9. Drift 확인, commit과 PR 전달 — 필수 완료 gate

Gitea Issue와 comments를 다시 읽어 approval snapshot의 body, updated_at과 comment baseline drift를 확인한다.
Broker Issue lease를 유지한 채 같은 handle에 acquire_repository를 request하고, 그 repository lease 아래 origin을 다시 fetch해 Gitea default branch SHA와 local ref를 확인한 뒤 release_repository를 request한다.
Default branch가 base 이후 전진했으면 자동 merge, rebase 또는 history rewrite하지 않는다. 새 변경이 구현과 충돌하지 않는지 판정할 수 없으면 delivery-ready로 보고하지 않는다.
Worktree의 base SHA, final HEAD, staged·unstaged·untracked 상태, 미완료 Git operation과 test 결과를 기록한다.
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하지 않는다.
기존 requirement revision이면 final tree에 Contract Preservation Inventory를 다시 대응해 missing=0, ambiguous=0을 확인한다. 충족하지 못하면 stage하거나 commit하지 않는다.
승인된 modified·untracked file을 exact allowlist로 stage하고 staged diff를 다시 읽는다. 범위 밖 파일, credential, generated artifact 또는 예상하지 못한 삭제가 있으면 commit하지 않는다.
Repository convention에 맞는 non-amended commit을 생성하고 base ancestry, commit tree와 worktree 상태를 검증한다. Push 전에 그 exact commit의 strict clean checkout에서 canonical external verification helper로 최종 검증을 실행·validate하고 manifest의 source SHA가 전달할 commit과 일치함을 확인한다. 실패하면 local commit을 보존하고 push하지 않는다.
Issue worktree는 delivery 전후 모두 detached HEAD로 유지한다. Issue 전용 remote branch가 없으면 detached final commit을 explicit repository URL과 <final-sha>:refs/heads/<issue-branch> refspec으로 push해 생성하고, 있으면 현재 작업이 소유한 branch이며 fast-forward 가능한 경우에만 같은 방식으로 갱신한다. git switch -c, git checkout -b, git branch 또는 동등한 명령으로 canonical mirror의 refs/heads/*에 구현용 local branch를 만들지 않는다. Default branch에는 직접 push하지 않고 force-push하지 않으며 canonical cache의 mirror remote 설정을 변경하지 않는다.
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를 보고한다.
Remote readback으로 branch owner, repository, branch SHA가 local commit SHA와 exact-match하는지 확인한다.
Default branch를 base로 PR을 생성한다. 제목은 Issue를 식별하고, 본문에는 Closes #<number>, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. PR 생성 자체로 Issue state를 변경하지 않는다.
PR 번호를 얻은 뒤 요구사항 문서의 구현 PR: 미정을 실제 PR 번호 또는 URL로 교체하고, 문서 검증과 관련 test를 재실행해 별도 commit으로 같은 branch에 non-force push한다.
Gitea에서 PR details, base branch, head repository·branch·SHA, state, changed files와 commit을 다시 읽는다. 최종 remote head SHA가 최종 local commit SHA와 일치할 때만 전달 완료로 판정한다.
Gitea Actions 또는 commit status가 제공되면 최종 head의 success, failed, pending, run 없음 또는 조회 불가 상태를 읽고 그대로 보고한다.
PR 생성 또는 후속 push가 부분 실패하면 blind retry하거나 중복 PR을 만들지 않는다. 이미 생성된 fork·branch·PR과 local commit의 exact 상태 및 안전한 복구 지점을 보고한다.
성공·실패와 관계없이 현재 실행이 만든 임시 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가 기록된 경우를 제외하고 스킬은 미완료다.

위임 규칙

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 결과
최종 보고와 PR에 재사용한 단일 검증 기록의 exact command, exit code와 pass·skip·fail 수치
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
최종 head의 Actions·commit status와 실제 runtime 검증을 대체한 경우의 미검증 범위
임시 process·workspace·credential helper 정리와 lock 해제 확인
수행한 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이 일치할 때만 구현 완료로 판정한다. Exact Issue 구현 요청에서 PR 생성은 별도 승인 대상이 아니라 완료 자체의 일부다.

Canonical external verification evidence

검증 실행 기록은 공통 Repository cache 운영 지침의 정본 경로 <harness-root>/repositories/<owner>/<repo>/worktrees/issue-<number>/verification/<run-id>에 보존한다. Product checkout과 artifact root를 분리하며, 회차별 evidence를 제품 docs/verification/에 새로 커밋하지 않는다. 기존 정본 문서·테스트·fixture·추적 파일은 자동 이동·삭제·ignore하지 않는다.

인증된 Issue/cache/worktree admission을 마친 caller가 broker Issue lease 아래 evidence run 전에 live lease의 exact harness root·Issue identity를 인증하고 root를 준비한다. Stage별 새 run-id를 사용한다. 아래 prepare는 verification/과 <run-id>/를 각각 별도 생성하고 각 directory를 실행 UID 소유 mode 0700으로 만들며 즉시 lstat한다. Symlink, owner·mode 불일치와 collision은 거부하고 기존 malformed root를 자동 chmod하거나 repair하지 않는다. 이 경로에는 중간 parent가 umask를 따르는 Path.mkdir(parents=True, mode=0o700)를 사용하지 않는다. Helper는 lease/cache를 획득·복구하지 않는다. <harness-root>는 실제로 읽은 contract path로 고정하고 다음 변수는 그 root와 인증된 Issue/run identity에서 결정한다. 아래 명령은 harness root에서 호출한다.

python3 harness/lib/verification_root.py prepare \
  --root "$HARNESS_ROOT" --owner "$OWNER" --repository "$REPOSITORY" \
  --issue "$ISSUE" --run-id "$RUN_ID" --handle "$HANDLE"
python3 harness/agents/impl/skills/gitea-issue-rework/scripts/evidence_manifest.py run \
  --contract-path "$HARNESS_ROOT/harness/operations/repository-cache.md" \
  --repo-root "$HARNESS_ROOT/repositories/$OWNER/$REPOSITORY/worktrees/issue-$ISSUE/checkout" \
  --artifact-root "$VERIFICATION_RUN_ROOT" \
  --plan evidence-plan.json --output evidence-manifest.json
python3 harness/agents/impl/skills/gitea-issue-rework/scripts/evidence_manifest.py validate \
  --contract-path "$HARNESS_ROOT/harness/operations/repository-cache.md" \
  --repo-root "$HARNESS_ROOT/repositories/$OWNER/$REPOSITORY/worktrees/issue-$ISSUE/checkout" \
  --artifact-root "$VERIFICATION_RUN_ROOT" \
  --manifest evidence-manifest.json

VERIFICATION_RUN_ROOT는 $HARNESS_ROOT/repositories/$OWNER/$REPOSITORY/worktrees/issue-$ISSUE/verification/$RUN_ID의 exact 절대 경로다. Plan의 hash_paths만 repository-relative이고 plan/output/manifest는 run-relative다. Source filename과 artifact filename이 같아도 같은 파일로 취급하지 않는다. run은 strict clean checkout, evidence exclusion 없음, full SHA·source/plan digest와 실제 command/exit code/bounded output binding을 요구하고 evidence-manifest/v2를 게시한다. Existing manifest를 덮어쓰지 않는다. validate도 같은 roots와 exact current HEAD를 요구한다. Dirty 개발 tree에서 validation 성공을 주장하지 않으며, final tracked 산출물을 commit한 뒤 그 exact commit을 검증하고 실패하면 push하지 않는다.

PR/결과 보고에는 stage/run-id, source SHA, manifest·plan digest, 실제 command/result/limitations와 reviewer 접근 수단을 함께 기록한다. Same-UID reviewer는 기록만 read-only로 읽고, distinct-UID/host이면 승인된 credential-free read-only export와 digest/readback receipt를 제공한다. 경로만 제시하거나 권한을 완화하는 것은 접근 검증이 아니다. 확인할 수 없으면 evidence_gap으로 보고한다. Product 테스트 증거와 harness 자체 검증을 구분하고, 인증정보 값은 [REDACTED]로만 기록한다.

Remote branch/PR head를 authoritative하게 읽어 source SHA·exact artifact와 결합하고 cleanup 전 실제 record readback을 확인한다. Helper의 local validate가 Gitea readback을 대신하지 않는다. Checkout 제거와 verification 폐기는 분리하며 완료 기록은 보존한다. 기존 v1은 validate-legacy의 read-only 호환 경로만 사용하고 새 publication proof로 사용하지 않는다.

34 KiB Raw Blame History