Initialize gitea-agent harness

2026-09-29 06:59:17 +00:00
commit c05b4226bf
20 changed files with 1840 additions and 0 deletions
@@ -0,0 +1,23 @@
+# 런타임 흐름 작성 방법
+
+런타임 흐름 문서는 승인된 Discovery와 구현 결과를 근거로 시작 이벤트부터 종료 상태까지의 실행 단계, 상태 변경 및 실패 복구 계약을 설명한다.
+
+## 저장 위치
+
+완성된 런타임 흐름 문서는 대상 저장소 루트 기준 `docs/runtime-flow.md`에 저장한다. 파일이 이미 존재하면 별도 문서를 만들지 않고 이 정본 문서를 갱신한다.
+
+이 디렉터리의 [`README.md`](README.md)와 [`TEMPLATE.md`](TEMPLATE.md)는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.
+
+## 작성 방법
+
+1. [`TEMPLATE.md`](TEMPLATE.md)를 복사하고 섹션 순서를 유지한다.
+2. 목적, 포함·제외 범위 및 흐름의 시작·종료 조건을 확정한다.
+3. `흐름`의 H3 블록을 독립 실행 흐름 수만큼 복제하고 단계 행을 실제 실행 순서대로 작성한다.
+4. 모든 `${lowercase_snake_case}` placeholder를 실제 값으로 교체한다. `${stable_section_id}`에는 고유한 소문자 케밥 표기법을 사용한다. 흐름 이름이 바뀌어도 ID는 유지하며 삭제된 ID를 재사용하지 않는다.
+5. 각 단계에 단계 ID, 실행 주체, 시작 조건·입력, 처리, 읽기·쓰기 상태, 외부 호출, 성공 시 다음 단계 및 실패 시 전이를 기록한다.
+6. 각 실패에 추가 쓰기 중단 여부, 재시도, 중복 방지, 보상·수동 복구 및 최종 상태를 기록한다.
+7. 동시 실행, 잠금·직렬화 단위, 순서 보장 및 충돌 처리를 기록한다.
+8. 로그·지표·추적 신호와 correlation ID, 진단 속성 및 민감정보 제거 규칙을 기록한다.
+9. 정상·실패·경계·동시성 흐름을 실제로 검증할 방법과 운영 진입점의 기대 결과를 기록한다.
+
+단계 ID는 문서 안에서 고유해야 하며 모든 다음 단계와 실패 전이는 실제 단계 또는 명시된 종료 상태를 가리켜야 한다. 근거 없이 흐름이나 동작을 추측하지 않는다. 해당 사항이 없으면 `없음`으로 기록한다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.
@@ -0,0 +1,51 @@
+# ${runtime_flow_title}
+
+## 목적과 범위
+
+${purpose}
+
+- 포함 범위: ${included_scope}
+- 제외 범위: ${excluded_scope}
+- 시작 조건: ${start_condition}
+- 성공 종료 상태: ${success_terminal_state}
+- 실패 종료 상태: ${failure_terminal_state}
+
+## 흐름
+
+### ${stable_section_id} — ${flow_name}
+
+- 시작 이벤트: ${trigger_event}
+- 선행조건: ${preconditions}
+- 실행 방식: ${synchronous_or_asynchronous}
+- 트랜잭션·영속성 경계: ${transaction_and_persistence_boundary}
+
+| 단계 ID | 실행 주체 | 시작 조건·입력 | 처리 | 읽기·쓰기 상태 | 외부 호출 | 성공 시 다음 단계 | 실패 시 전이 |
+|---|---|---|---|---|---|---|---|
+| `${step_id}` | ${actor_or_component} | ${step_condition_and_input} | ${processing} | ${state_reads_and_writes} | ${external_call_or_none} | `${success_next_step_or_terminal}` | `${failure_transition_or_terminal}` |
+
+## 실패와 복구
+
+| 대상 단계 | 실패 조건 | 추가 쓰기 중단 | 재시도 계약 | 중복 방지 | 보상·수동 복구 | 최종 상태 |
+|---|---|---|---|---|---|---|
+| `${failed_step_id}` | ${failure_condition} | ${stop_further_writes} | ${retry_contract} | ${idempotency_contract} | ${compensation_or_manual_recovery} | `${failure_final_state}` |
+
+### 동시성과 순서
+
+- 동시 실행 허용 여부: ${concurrent_execution_policy}
+- 잠금·직렬화 단위: ${locking_or_serialization_scope}
+- 순서 보장: ${ordering_guarantee}
+- 충돌 검출·처리: ${conflict_detection_and_handling}
+
+## 관찰 가능성
+
+| 신호 종류 | 이름 | 발생 단계·조건 | 상관 식별자 | 진단 속성 | 민감정보 처리 |
+|---|---|---|---|---|---|
+| ${signal_type} | `${signal_name}` | ${signal_step_and_condition} | ${correlation_identifier} | ${diagnostic_attributes} | ${sensitive_data_handling} |
+
+## 검증
+
+- 정상 흐름: ${success_flow_validation}
+- 실패 흐름: ${failure_flow_validation}
+- 경계 흐름: ${boundary_flow_validation}
+- 동시성 흐름: ${concurrency_flow_validation}
+- 운영 진입점과 기대 결과: ${operational_entry_point_and_expected_result}