From 37545680d68e22578adbb1a1127ec2797987835c Mon Sep 17 00:00:00 2001 From: gitea-spec-agent Date: Fri, 2 Oct 2026 08:25:13 +0000 Subject: [PATCH] docs(impl): preserve requirement contract inventory --- .../gitea-issue-implementation/SKILL.md | 31 +++++++++-------- .../impl/skills/gitea-issue-rework/SKILL.md | 34 +++++++++++++++---- 2 files changed, 44 insertions(+), 21 deletions(-) diff --git a/harness/agents/impl/skills/gitea-issue-implementation/SKILL.md b/harness/agents/impl/skills/gitea-issue-implementation/SKILL.md index 327b2c9..c7821e7 100644 --- a/harness/agents/impl/skills/gitea-issue-implementation/SKILL.md +++ b/harness/agents/impl/skills/gitea-issue-implementation/SKILL.md @@ -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--`처럼 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 #`, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. 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 #`, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. 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 정리가 검증됐다. diff --git a/harness/agents/impl/skills/gitea-issue-rework/SKILL.md b/harness/agents/impl/skills/gitea-issue-rework/SKILL.md index 667cbe5..46f1f7b 100644 --- a/harness/agents/impl/skills/gitea-issue-rework/SKILL.md +++ b/harness/agents/impl/skills/gitea-issue-rework/SKILL.md @@ -1,7 +1,7 @@ --- name: gitea-issue-rework description: Gitea PR 검토 지적을 계약에 맞춰 재작업하고 검증한다. -version: 0.2.3 +version: 0.2.4 author: genichin, Hermes Agent license: MIT platforms: [linux] @@ -73,6 +73,25 @@ Repository file을 수정하기 전에 다음을 모두 검증한다. - 전체 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`이어야 한다. + 모든 finding을 다음 matrix의 정확히 한 항목으로 분류한다. ```text @@ -92,7 +111,7 @@ reason: - `reviewer_misunderstanding`: 지적이 승인 계약 밖의 새 요구사항이거나 authoritative tree와 맞지 않는다. 이를 만족시키려고 범위를 확장하지 않고 근거와 함께 unresolved로 보고한다. - `blocked_spec`: 명세 모순이나 새 결정이 필요하다. 모든 repository write를 중단한다. -완료 조건: 모든 review finding과 unsatisfied·indeterminate criterion이 matrix에 정확히 한 번 나타나고, `valid_fix`와 `evidence_gap`마다 변경 또는 검증 경로가 있으며, 이미 satisfied인 계약을 약화하는 항목이 없다. +완료 조건: 모든 review finding과 unsatisfied·indeterminate criterion이 matrix에 정확히 한 번 나타나고, `valid_fix`와 `evidence_gap`마다 변경 또는 검증 경로가 있으며, 이미 satisfied인 계약을 약화하는 항목이 없다. Contract Preservation Inventory가 필요한 경우 baseline 전체가 대응되고 `missing=0`, `ambiguous=0`이다. ## Canonical 재작업 결과 comment @@ -206,12 +225,13 @@ Reviewer가 rework head를 새 snapshot으로 다시 검토해야 하며 이 com 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. Exact allowlist만 stage하고 staged diff를 다시 읽는다. -5. Repository convention에 맞는 새 non-amended rework commit을 생성한다. Review별 traceability가 필요하면 commit message나 검증 기록에 PR과 review ID를 포함하되 review body를 그대로 복제하지 않는다. -6. Commit 후 clean HEAD에서 최종 formatter, test와 필요한 runtime·browser 검증을 다시 실행한다. 이 뒤 repository file을 바꾸면 영향을 받은 검증을 다시 실행한다. -7. 최종 검증 기록은 exact HEAD 또는 검증한 source tree, command, exit code, pass·skip·fail 수치, 환경, relevant output과 artifact path를 포함한다. Tracked evidence가 final HEAD 자체를 포함할 수 없어 evidence-only descendant가 생기면 검증한 commit과 final head의 ancestry 및 검증 대상 path가 불변임을 명시하고 숨기지 않는다. +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과 artifact path를 포함한다. Tracked evidence가 final HEAD 자체를 포함할 수 없어 evidence-only descendant가 생기면 검증한 commit과 final head의 ancestry 및 검증 대상 path가 불변임을 명시하고 숨기지 않는다. -완료 조건: final local HEAD, clean state, finding별 해결 evidence와 단일 검증 기록이 일치한다. +완료 조건: final local HEAD, clean state, finding별 해결 evidence와 단일 검증 기록이 일치하며, 필요한 Contract Preservation Inventory는 `missing=0`, `ambiguous=0`이다. ### 7. 기존 PR branch 전달