docs(impl): preserve requirement contract inventory
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: gitea-issue-implementation
|
||||
description: 승인된 Gitea Issue를 구현·검증하고 Gitea PR로 전달한다.
|
||||
version: 0.4.1
|
||||
version: 0.4.2
|
||||
author: genichin, Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux]
|
||||
@@ -90,8 +90,9 @@ Issue body와 `updated_at`을 immutable approval snapshot으로 보존한다. bo
|
||||
3. 각 문서의 조치, exact path와 필수 내용을 추출한다. `영향 없음`인 문서를 생성하지 않는다.
|
||||
4. 사용자 관찰 가능 동작, 실패 동작, 보안 불변조건, 호환성 조건과 외부 write 경계를 acceptance matrix로 만든다.
|
||||
5. 각 acceptance criterion에 예정된 문서, source 위치와 검증 test를 연결한다. 연결할 수 없는 criterion이 있으면 구현 전에 중단한다.
|
||||
6. 기존 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의 한 항목 이상에 대응하고, 제외 범위가 구현 항목에 포함되지 않는다.
|
||||
완료 조건: 모든 확정된 결정과 산출물이 acceptance matrix의 한 항목 이상에 대응하고, 제외 범위가 구현 항목에 포함되지 않는다. 기존 requirement revision이면 baseline 전체가 inventory에 중복 없이 정확히 한 번 대응하고 repository 첫 write 전 계획 기준 `missing=0`, `ambiguous=0`이다.
|
||||
|
||||
### 3. Cache 검증과 base 결정
|
||||
|
||||
@@ -139,8 +140,9 @@ Discovery가 `신규 작성` 또는 `수정`으로 판정한 문서만 작성한
|
||||
5. 런타임 흐름은 영향이 있을 때 harness의 [런타임 흐름 작성 방법](../../../../docs/runtime-flow/README.md)과 [런타임 흐름 템플릿](../../../../docs/runtime-flow/TEMPLATE.md)을 적용한다.
|
||||
6. Requirement frontmatter는 canonical `gitea-agent.requirement/v1` 계약을 만족하고 status를 `approved`로 기록한다. 구현 PR이 아직 없으면 `미정`을 유지하고 번호를 추측하지 않는다.
|
||||
7. 모든 placeholder, 작성 안내 문구, 실제 credential과 확인되지 않은 경로를 제거한다.
|
||||
8. 기존 requirement revision이면 작성 결과에 Contract Preservation Inventory를 다시 대응하고 `missing=0`, `ambiguous=0`을 검증한다. 충족하지 못하면 문서 작성 완료로 판정하지 않는다.
|
||||
|
||||
완료 조건: Discovery의 문서 영향 판정과 생성·수정된 문서 집합이 정확히 일치하고 각 문서가 해당 README와 TEMPLATE 검증을 통과한다.
|
||||
완료 조건: Discovery의 문서 영향 판정과 생성·수정된 문서 집합이 정확히 일치하고 각 문서가 해당 README와 TEMPLATE 검증을 통과하며, 필요한 Contract Preservation Inventory는 `missing=0`, `ambiguous=0`이다.
|
||||
|
||||
### 7. Test-first 구현
|
||||
|
||||
@@ -174,17 +176,18 @@ Discovery가 `신규 작성` 또는 `수정`으로 판정한 문서만 작성한
|
||||
3. Default branch가 base 이후 전진했으면 자동 merge, rebase 또는 history rewrite하지 않는다. 새 변경이 구현과 충돌하지 않는지 판정할 수 없으면 delivery-ready로 보고하지 않는다.
|
||||
4. Worktree의 base SHA, final HEAD, staged·unstaged·untracked 상태, 미완료 Git operation과 test 결과를 기록한다.
|
||||
5. Branch 이름은 repository convention이 있으면 이를 따르고, 없으면 `gitea-agent/issue-<number>-<short-slug>`처럼 deterministic Issue 전용 이름을 사용한다. Gitea와 remote에서 동일 이름의 branch와 열린 PR을 먼저 조회해 중복 생성하지 않는다.
|
||||
6. 승인된 modified·untracked file을 exact allowlist로 stage하고 staged diff를 다시 읽는다. 범위 밖 파일, credential, generated artifact 또는 예상하지 못한 삭제가 있으면 commit하지 않는다.
|
||||
7. Repository convention에 맞는 non-amended commit을 생성하고 base ancestry, commit tree와 worktree 상태를 검증한다.
|
||||
8. Issue 전용 branch가 없으면 final commit을 가리키도록 생성하고, 있으면 현재 작업이 소유한 branch이며 fast-forward 가능한 경우에만 갱신한다. Default branch에는 직접 push하지 않고 force-push하지 않는다. Canonical cache의 mirror remote 설정을 변경하지 말고 push할 때 explicit repository URL과 refspec을 사용한다.
|
||||
9. 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를 보고한다.
|
||||
10. Remote readback으로 branch owner, repository, branch SHA가 local commit SHA와 exact-match하는지 확인한다.
|
||||
11. Default branch를 base로 PR을 생성한다. 제목은 Issue를 식별하고, 본문에는 `Closes #<number>`, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. PR 생성 자체로 Issue state를 변경하지 않는다.
|
||||
12. PR 번호를 얻은 뒤 요구사항 문서의 `구현 PR: 미정`을 실제 PR 번호 또는 URL로 교체하고, 문서 검증과 관련 test를 재실행해 별도 commit으로 같은 branch에 non-force push한다.
|
||||
13. Gitea에서 PR details, base branch, head repository·branch·SHA, state, changed files와 commit을 다시 읽는다. 최종 remote head SHA가 최종 local commit SHA와 일치할 때만 전달 완료로 판정한다.
|
||||
14. Gitea Actions 또는 commit status가 제공되면 최종 head의 success, failed, pending, run 없음 또는 조회 불가 상태를 읽고 그대로 보고한다.
|
||||
15. PR 생성 또는 후속 push가 부분 실패하면 blind retry하거나 중복 PR을 만들지 않는다. 이미 생성된 fork·branch·PR과 local commit의 exact 상태 및 안전한 복구 지점을 보고한다.
|
||||
16. 성공·실패와 관계없이 현재 실행이 만든 임시 server, fixture workspace와 credential helper를 정리하고 부재를 확인한 뒤 현재 실행이 획득한 lock을 해제한다. Persistent Issue worktree는 별도 제거 승인이 없으면 보존한다.
|
||||
6. 기존 requirement revision이면 final tree에 Contract Preservation Inventory를 다시 대응해 `missing=0`, `ambiguous=0`을 확인한다. 충족하지 못하면 stage하거나 commit하지 않는다.
|
||||
7. 승인된 modified·untracked file을 exact allowlist로 stage하고 staged diff를 다시 읽는다. 범위 밖 파일, credential, generated artifact 또는 예상하지 못한 삭제가 있으면 commit하지 않는다.
|
||||
8. Repository convention에 맞는 non-amended commit을 생성하고 base ancestry, commit tree와 worktree 상태를 검증한다.
|
||||
9. Issue 전용 branch가 없으면 final commit을 가리키도록 생성하고, 있으면 현재 작업이 소유한 branch이며 fast-forward 가능한 경우에만 갱신한다. Default branch에는 직접 push하지 않고 force-push하지 않는다. Canonical cache의 mirror remote 설정을 변경하지 말고 push할 때 explicit repository URL과 refspec을 사용한다.
|
||||
10. 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를 보고한다.
|
||||
11. Remote readback으로 branch owner, repository, branch SHA가 local commit SHA와 exact-match하는지 확인한다.
|
||||
12. Default branch를 base로 PR을 생성한다. 제목은 Issue를 식별하고, 본문에는 `Closes #<number>`, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. PR 생성 자체로 Issue state를 변경하지 않는다.
|
||||
13. PR 번호를 얻은 뒤 요구사항 문서의 `구현 PR: 미정`을 실제 PR 번호 또는 URL로 교체하고, 문서 검증과 관련 test를 재실행해 별도 commit으로 같은 branch에 non-force push한다.
|
||||
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는 별도 제거 승인이 없으면 보존한다.
|
||||
|
||||
완료 조건: Issue와 source drift, final worktree 상태와 실행 결과가 fresh readback으로 확인되고, 열린 Gitea PR의 base·head와 remote head SHA가 검증된 최종 local commit에 exact-match하며, 임시 resource와 lock 정리가 검증됐다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user