Initialize gitea-agent harness

harness/docs/data-model/README.md

@@ -0,0 +1,22 @@
+# 데이터 모델 작성 방법
+
+데이터 모델 문서는 승인된 Discovery와 구현 결과를 근거로 구현 완료 후의 정본 데이터 구조를 설명한다.
+
+## 저장 위치
+
+완성된 데이터 모델 문서는 대상 저장소 루트 기준 `docs/data-model.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. 각 필드 행에 필드명, 타입, 필수 여부, 기본값, 허용 값·형식, 단위·정밀도 및 민감정보 여부를 기록한다. 해당 값이 없으면 `없음`으로 기록한다.
+6. 관계의 방향과 카디널리티, 소유권, 삭제 규칙 및 항상 유지해야 하는 불변조건을 기록한다.
+7. 저장 위치와 직렬화 형식, 기존 데이터 마이그레이션, 하위 호환성 및 롤백 조건을 기록한다.
+8. 정상·경계·오류 데이터와 저장 후 재조회·마이그레이션 검증 방법을 기록한다.
+
+근거 없이 엔터티나 필드를 추측하지 않는다. 해당 사항이 없으면 `없음`으로 기록하고, 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.

harness/docs/data-model/TEMPLATE.md

@@ -0,0 +1,51 @@
+# ${data_model_title}
+
+## 목적과 범위
+
+${purpose}
+
+- 포함 범위: ${included_scope}
+- 제외 범위: ${excluded_scope}
+
+## 정본 엔터티
+
+### ${stable_section_id} — ${entity_name}
+
+- 책임: ${entity_responsibility}
+- 식별자: `${identifier_field}`
+- 생명 주기: ${entity_lifecycle}
+
+#### 필드
+
+| 필드 | 타입 | 필수 여부 | 기본값 | 허용 값·형식 | 단위·정밀도 | 민감정보 |
+|---|---|---|---|---|---|---|
+| `${field_name}` | `${field_type}` | ${required_or_optional} | ${default_value_or_none} | ${allowed_values_and_format} | ${unit_and_precision_or_none} | ${sensitivity_or_none} |
+
+## 관계와 불변조건
+
+### 관계
+
+| 출발 엔터티 | 관계 | 대상 엔터티 | 카디널리티 | 필수 여부 | 소유권 | 삭제 규칙 |
+|---|---|---|---|---|---|---|
+| `${source_entity_id}` | ${relationship} | `${target_entity_id}` | `${cardinality}` | ${required_or_optional} | ${ownership} | ${deletion_rule} |
+
+### 불변조건
+
+- ${invariant}
+
+## 저장과 마이그레이션
+
+- 저장 위치: ${storage_location}
+- 직렬화 형식: ${serialization_format}
+- 스키마 버전: ${schema_version}
+- 기존 데이터 처리: ${existing_data_migration}
+- 하위 호환성: ${backward_compatibility}
+- 롤백 조건: ${rollback_conditions}
+
+## 검증
+
+- 정상 데이터: ${normal_data_validation}
+- 경계 데이터: ${boundary_data_validation}
+- 오류 데이터: ${invalid_data_validation}
+- 저장 후 재조회: ${round_trip_validation}
+- 마이그레이션: ${migration_validation}

harness/docs/discovery/README.md

@@ -0,0 +1,66 @@
+# Discovery 작성 방법
+
+Discovery는 Gitea Issue 본문으로 작성한다.
+
+1. [`TEMPLATE.md`](TEMPLATE.md)를 복사한다.
+2. 첫 번째 marker와 섹션 순서를 유지한다.
+3. `${...}` placeholder를 저장소 근거에 기반한 한국어 내용으로 교체한다.
+4. 템플릿에 없는 hidden state, marker 또는 metadata를 추가하지 않는다.
+5. 미해결 질문이 없으면 `없음`으로 작성한다.
+
+## Discovery marker 정책
+
+`<!-- gitea-agent:discovery-draft/v2 -->`는 Discovery body의 문서 유형과 템플릿 버전을 식별하는 marker다.
+
+- body의 첫 줄에 exact bytes로 한 번만 둔다.
+- marker에 속성, 상태 또는 payload를 추가하지 않는다.
+- 작성·검증·재실행 시 marker와 템플릿의 섹션 순서를 함께 확인한다.
+- marker가 없거나 값이 다르거나 알 수 없는 버전이면 유효한 Discovery 초안으로 취급하지 않는다.
+- 다른 버전을 임의로 생성하거나 자동 변환하지 않는다.
+
+각 섹션에는 요약, 문제, 포함·제외 범위, 제약 조건, 확정된 결정, 저장소 근거, 문서 영향과 미해결 질문을 기록한다.
+
+## 문서 영향 및 산출물 작성 방법
+
+`문서 영향 및 산출물`에는 다음 문서 유형을 순서대로 모두 기록한다. 영향이 없는 문서도 생략하지 않는다.
+
+1. 요구사항명세서 — `docs/requirements/req-NNN_<slug>.md` 형식의 exact 경로
+2. 데이터 모델 — `docs/data-model.md`
+3. 인터페이스 계약 — `docs/interface-contract.md`
+4. 프로젝트 구조 — `docs/project-structure.md`
+5. 런타임 흐름 — `docs/runtime-flow.md`
+
+각 문서 유형은 다음 형식으로 작성한다.
+
+```markdown
+### 문서 이름
+
+- 조치: 신규 작성 | 갱신 | 영향 없음
+- 경로: `대상 저장소 기준 경로`
+- 변경 내용: 추가하거나 변경할 계약과 범위
+- 근거: Discovery 범위 또는 pinned source revision에서 확인한 저장소 근거
+```
+
+- `조치`는 세 값 중 하나만 사용한다.
+- pinned source revision에 정본 문서가 없고 문서 영향이 있으면 `신규 작성`, 정본 문서가 있고 문서 영향이 있으면 `갱신`으로 기록한다.
+- `영향 없음`인 경우에도 변경 내용에 영향이 없는 이유를 기록한다.
+- 요구사항명세서는 pinned source revision의 기존 `docs/requirements/req-NNN_<slug>.md` 파일을 조사해 충돌하지 않는 `REQ-NNN`을 결정하고, 확정된 범위를 나타내는 소문자 ASCII 케밥 표기법의 slug를 사용해 exact 경로를 기록한다. README와 TEMPLATE는 할당된 요구사항 ID로 세지 않는다.
+- 기존 요구사항 파일이 없으면 `REQ-001`부터 시작한다. 기존 ID가 `REQ-001`부터 빠짐없이 연속이면 가장 큰 ID의 다음 값을 사용한다. 기존 ID가 중복·비연속·형식 오류 상태이거나 exact 파일명을 안전하게 결정할 수 없으면 값을 추측하지 않고 Discovery 작성을 중단한다.
+- 요구사항명세서 항목에는 `문서 ID`, `제목`, `포함할 내용`, `제외할 내용`을 추가한다. 포함할 내용은 구현 에이전트가 요구사항과 acceptance criteria로 내려야 할 동작, 오류, 보안, 데이터·인터페이스, 호환성 및 추적성 계약을 구체적으로 나열한다.
+- 데이터 모델은 변경할 엔터티·필드·관계·불변조건·마이그레이션을, 인터페이스 계약은 입력·출력·인증·오류·호환성을, 프로젝트 구조는 경로·책임·의존 방향·배치 규칙을, 런타임 흐름은 시작 조건·단계·상태 변경·외부 호출·실패 복구·동시성·관찰 가능성을 변경 내용에 기록한다.
+- 문서가 `영향 없음`이면 해당 문서 계약이 왜 바뀌지 않는지 확정 범위와 저장소 근거를 사용해 설명한다.
+- 변경 내용에는 구현 에이전트가 문서에 반영할 계약과 범위만 기록한다. Discovery 작성 중 후속 문서를 생성하거나 수정하지 않는다.
+- 저장소 근거나 확정된 결정 없이 엔터티, 인터페이스, 디렉터리, 실행 흐름 또는 문서 변경을 만들어내지 않는다.
+
+## OQ(${open_questions}) 작성 방법
+
+각 OQ에는 질문에 대한 설명과 선택지를 작성하고 추천안을 표시한다. 모든 선택지는 체크박스(`[ ]`)를 사용한다.
+
+```markdown
+### OQ-001 — 질문
+
+질문에 대한 설명
+
+- [ ] 선택지 A (추천)
+- [ ] 선택지 B
+```

harness/docs/discovery/TEMPLATE.md

@@ -0,0 +1,36 @@
+<!-- gitea-agent:discovery-draft/v2 -->
+## 요약
+
+${summary}
+
+## 문제
+
+${problem}
+
+## 포함 범위
+
+${in_scope}
+
+## 제외 범위
+
+${out_of_scope}
+
+## 제약 조건
+
+${constraints}
+
+## 확정된 결정
+
+${confirmed_decisions}
+
+## 저장소 근거
+
+${repository_evidence}
+
+## 문서 영향 및 산출물
+
+${documentation_impact}
+
+## 미해결 질문
+
+${open_questions}

harness/docs/interface-contract/README.md

@@ -0,0 +1,22 @@
+# 인터페이스 계약 작성 방법
+
+인터페이스 계약 문서는 승인된 Discovery와 구현 결과를 근거로 외부·내부 인터페이스의 호출 규칙을 설명한다.
+
+## 저장 위치
+
+완성된 인터페이스 계약 문서는 대상 저장소 루트 기준 `docs/interface-contract.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. 각 인터페이스의 책임, 종류·프로토콜, 호출 대상, 버전, 호출 주체, 인증·권한을 기록한다.
+6. 입력·출력 필드와 오류 계약을 표에 기록한다. 값이 없으면 `없음`으로 기록한다.
+7. 기존 호출 방식, 버전 변경·폐기, 재시도·중복 처리 및 순서 보장에 대한 호환성 계약을 기록한다.
+8. 실제 구현과 일치하는 호출 예시와 정상·실패·경계 계약의 검증 방법을 기록한다. 예시에는 실제 credential이나 민감정보를 포함하지 않는다.
+
+근거 없이 인터페이스나 동작을 추측하지 않는다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.

harness/docs/interface-contract/TEMPLATE.md

@@ -0,0 +1,73 @@
+# ${interface_contract_title}
+
+## 목적과 범위
+
+${purpose}
+
+- 포함 범위: ${included_scope}
+- 제외 범위: ${excluded_scope}
+- 사용 주체: ${consumers}
+
+## 계약
+
+### ${stable_section_id} — ${interface_name}
+
+- 책임: ${responsibility}
+- 종류·프로토콜: ${interface_type_and_protocol}
+- 호출 대상·operation: ${target_and_operation}
+- 버전: ${version}
+- 호출 주체: ${caller}
+- 인증 방식: ${authentication}
+- 필요 권한: ${authorization}
+
+#### 입력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 기본값 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|---|
+| `${input_field_name}` | ${input_location} | `${input_type}` | ${input_required_or_optional} | ${input_default_or_none} | ${input_constraints} | ${input_meaning} | ${input_sensitivity_or_none} |
+
+#### 출력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|
+| `${output_field_name}` | ${output_location} | `${output_type}` | ${output_required_or_optional} | ${output_constraints} | ${output_meaning} | ${output_sensitivity_or_none} |
+
+#### 오류
+
+| 코드 | 분류 | 발생 조건 | 재시도 가능 여부 | 호출자 대응 | 실패 시 상태 변경 |
+|---|---|---|---|---|---|
+| `${error_code}` | ${error_class} | ${error_condition} | ${retryability} | ${caller_action} | ${state_change_or_none} |
+
+## 호환성
+
+- 유지할 기존 호출 방식: ${existing_call_compatibility}
+- 버전 변경 정책: ${versioning_policy}
+- 폐기 정책: ${deprecation_policy}
+- 재시도 계약: ${retry_contract}
+- 중복 처리 계약: ${idempotency_contract}
+- 순서 보장: ${ordering_guarantee}
+
+## 예시
+
+### ${example_id} — ${example_title}
+
+- 대상 인터페이스: `${target_interface_id}`
+
+#### 호출
+
+```text
+${request_or_call_example}
+```
+
+#### 결과
+
+```text
+${response_or_result_example}
+```
+
+## 검증
+
+- 정상 계약: ${success_contract_validation}
+- 실패 계약: ${failure_contract_validation}
+- 경계 계약: ${boundary_contract_validation}
+- 구현·스키마·예시 정합성: ${implementation_schema_example_consistency}

harness/docs/project-structure/README.md

@@ -0,0 +1,22 @@
+# 프로젝트 구조 작성 방법
+
+프로젝트 구조 문서는 승인된 Discovery와 구현 결과를 근거로 저장소의 구성 원칙, 영역별 책임 및 의존 경계를 설명한다.
+
+## 저장 위치
+
+완성된 프로젝트 구조 문서는 대상 저장소 루트 기준 `docs/project-structure.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. 각 경로의 종류, 책임, 공개 진입점, 내부 구현 경계, 편집 정책 및 생성 주체를 기록한다. 행은 실제 경로 수만큼 복제한다.
+6. 영역 간 의존마다 출발·대상 영역, 허용 여부, 규칙 및 공유 계약 위치를 기록한다. 역방향 또는 순환 의존은 명시적으로 금지한다.
+7. 새 모듈과 파일의 배치, 이름·패키지 및 소스·테스트 대응 규칙을 기록한다.
+8. 실제로 실행 가능한 구조 검사와 정적 분석 명령, 기대 결과 및 문서와 실제 트리의 정합성 확인 방법을 기록한다.
+
+경로는 대상 저장소 루트 기준으로 작성하고 근거 없이 영역이나 규칙을 추측하지 않는다. 해당 사항이 없으면 `없음`으로 기록한다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.

harness/docs/project-structure/TEMPLATE.md

@@ -0,0 +1,53 @@
+# ${project_structure_title}
+
+## 목적과 경계
+
+${purpose}
+
+- 포함 경계: ${included_boundary}
+- 제외 경계: ${excluded_boundary}
+
+## 디렉터리 구조
+
+### ${stable_section_id} — ${area_name}
+
+```text
+${directory_tree}
+```
+
+| 경로 | 종류 | 책임 | 공개 진입점 | 내부 구현 경계 | 편집 정책 | 생성 주체 |
+|---|---|---|---|---|---|---|
+| `${repository_relative_path}` | ${path_type} | ${responsibility} | ${public_entry_point_or_none} | ${internal_boundary} | ${edit_policy} | ${generator_or_none} |
+
+## 의존 방향
+
+| 출발 영역 | 대상 영역 | 허용 여부 | 규칙 | 공유 계약 위치 |
+|---|---|---|---|---|
+| `${source_area_id}` | `${target_area_id}` | ${allowed_or_forbidden} | ${dependency_rule} | ${shared_contract_path_or_none} |
+
+## 변경 규칙
+
+| 구분 | 규칙 |
+|---|---|
+| 새 모듈·파일 배치 | ${module_and_file_placement_rule} |
+| 이름·패키지 | ${naming_and_package_rule} |
+| 소스·테스트 대응 | ${source_test_mapping_rule} |
+| 생성 산출물 | ${generated_artifact_rule} |
+
+## 검증
+
+- 구조 검사 명령:
+
+  ```text
+  ${structure_validation_command}
+  ```
+
+- 구조 검사 기대 결과: ${structure_validation_expected_result}
+- 정적 분석 명령:
+
+  ```text
+  ${static_analysis_command}
+  ```
+
+- 정적 분석 기대 결과: ${static_analysis_expected_result}
+- 문서와 실제 트리의 정합성: ${document_tree_consistency_validation}

harness/docs/requirements/README.md

@@ -0,0 +1,107 @@
+# 요구사항
+
+각 요구사항 문서는 Markdown 본문 앞에 JSON 프런트 매터를 둔다.
+
+## 정본
+
+요구사항 작성·검토에는 이 디렉터리의 `README.md`와 `TEMPLATE.md` 및 이와 byte parity가 검증된 trusted bundle만 정본으로 사용한다. 대상 저장소에 기존 `docs/requirements/README.md` 또는 `docs/requirements/TEMPLATE.md`가 있더라도 그 내용·schema·lifecycle·문서 구조를 작성 정책이나 템플릿으로 사용하지 않는다. 대상 저장소에서는 실제 `req-NNN_<slug>.md` 파일만 ID 충돌과 기존 정본 산출물 여부를 판정하기 위해 조사한다.
+
+## 저장 위치
+
+완성된 요구사항명세서는 대상 저장소 루트 기준 다음 경로에 저장한다.
+
+```text
+docs/requirements/req-NNN_<slug>.md
+```
+
+같은 `REQ-NNN`의 문서가 이미 존재하면 별도 파일을 만들지 않고 기존 정본 문서를 갱신한다. 이 디렉터리의 [`README.md`](README.md)와 [`TEMPLATE.md`](TEMPLATE.md)는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.
+
+## 파일 이름 규칙
+
+```text
+req-NNN_<slug>.md
+```
+
+- `NNN`: 요구사항 ID를 나타내는 세 자리 십진수
+- `<slug>`: 요구사항 제목을 나타내는 소문자 케밥 표기법의 ASCII 슬러그
+
+## 메타데이터 스키마
+
+```json
+{
+  "schema": "gitea-agent.requirement/v1",
+  "id": "${requirement_id}",
+  "title": "${title}",
+  "revision": "1.0",
+  "status": "approved",
+  "depends_on": [],
+  "applies_to": ["${product_area}"],
+  "language": "ko"
+}
+```
+
+- `id`: 저장소 안에서 고유한 `REQ-NNN` 형식의 요구사항 식별자. 파일 이름의 `NNN` 및 H1과 일치해야 한다.
+- `revision`: 최초 작성 시 `1.0`으로 시작하며 요구사항의 의미가 변경될 때 올린다.
+- `status`: 구현 에이전트가 승인된 Discovery를 근거로 작성하므로 항상 `approved`로 기록한다. 다른 값은 허용하지 않는다.
+- `depends_on`: 선행 요구사항 식별자 배열. 선행 요구사항이 없으면 빈 배열을 사용한다.
+- `applies_to`: 요구사항이 적용되는 제품 영역 식별자 배열. 하나 이상의 값을 기록한다.
+
+### 메타데이터 배열 규칙
+
+- 배열 값은 중복 없이 안정적인 순서로 기록한다.
+- `depends_on` 값은 같은 저장소의 유효한 `REQ-NNN`만 허용하며 자기 자신과 직접·간접 순환 참조를 금지한다.
+- `applies_to` 값은 소문자 케밥 표기법의 제품 영역 식별자를 사용한다.
+
+## Placeholder와 반복 블록
+
+- 교체 대상은 `${lowercase_snake_case}` 형식만 사용한다.
+- TEMPLATE의 모든 `${...}` placeholder를 실제 값으로 교체하며 완성 문서에 하나도 남기지 않는다.
+- `## 5. 요구사항`의 H3 블록은 독립 요구사항 수만큼 복제하고 `REQ-NNN.01`부터 연속 식별자를 부여한다.
+- `## 7. 인수 기준`의 H3 블록은 각 요구사항에 하나 이상 두고 `REQ-NNN.XX-AC01`부터 요구사항별로 연속 식별자를 부여한다.
+- 사용하지 않는 예시 블록이나 작성 안내 문구를 완성 문서에 남기지 않는다.
+
+## 완성 문서 검증
+
+- 파일 이름의 `NNN`, 프런트 매터의 `id`, H1의 요구사항 식별자가 일치해야 한다.
+- 요구사항과 인수 기준 식별자는 각각 `01`부터 빠짐없이 연속되어야 한다.
+- 모든 필수 섹션을 채우고 해당 사항이 없으면 `없음`으로 기록한다.
+- 프런트 매터는 유효한 JSON이어야 하며 `schema`, `status`, `language`는 정해진 값을 정확히 사용해야 한다.
+
+## 제약과 불변조건 작성 방법
+
+구현 방식과 무관하게 유지해야 하는 데이터·상태·보안·원자성·정밀도·동시성·순서 조건을 기록한다. 하위 호환성은 이 섹션에 중복하지 않는다.
+
+## 하위 호환성 작성 방법
+
+문서 전체에 적용되는 공통 하위 호환 계약을 기록한다.
+
+- 유지해야 하는 기존 API, 설정, 데이터, 사용자 흐름을 명시한다.
+- 의도적으로 변경되는 동작은 적용 경계와 마이그레이션 방법을 함께 기록한다.
+- 개별 요구사항에만 해당하는 내용은 해당 요구사항의 `영향 범위 > 호환성`에 기록한다.
+- 기존 계약에 영향이 없으면 `없음`으로 기록한다.
+
+## 추적성 작성 방법
+
+요구사항명세서는 구현 에이전트가 승인된 Discovery를 근거로 초기 구현과 함께 작성한다.
+
+- 같은 저장소의 근거 이슈는 `#NNN` 형식으로 기록한다.
+- 초기 작성 시점에는 구현 PR이 아직 없으므로 `구현 PR`은 `미정`으로 기록하며 번호를 추측하지 않는다.
+- 다른 저장소의 Issue 또는 PR을 참조할 때는 `owner/repository#NNN` 형식으로 저장소를 명시한다.
+- 관련 설계 문서는 저장소 기준 상대 경로로 기록한다.
+- 관련 요구사항은 `REQ-NNN` 식별자로 기록한다.
+- 여러 값은 쉼표로 구분하고, 해당 항목이 없으면 `없음`으로 기록한다.
+
+## Python 파싱
+
+프런트 매터 본문은 JSON이므로 별도 의존성 없이 Python 표준 라이브러리로 읽을 수 있다.
+
+```python
+import json
+from pathlib import Path
+
+text = Path("docs/requirements/req-001_algorithm-input-contract.md").read_text(encoding="utf-8")
+_, metadata_json, _ = text.split("---", 2)
+metadata = json.loads(metadata_json)
+```
+
+JSON 프런트 매터의 `revision`과 `status`가 문서의 기준값이다.

harness/docs/requirements/TEMPLATE.md

@@ -0,0 +1,96 @@
+---
+{
+  "schema": "gitea-agent.requirement/v1",
+  "id": "${requirement_id}",
+  "title": "${title}",
+  "revision": "1.0",
+  "status": "approved",
+  "depends_on": [],
+  "applies_to": ["${product_area}"],
+  "language": "ko"
+}
+---
+
+# ${requirement_id} — ${title}
+
+## 1. 목적
+
+${purpose}
+
+## 2. 배경
+
+${background}
+
+## 3. 범위
+
+### 포함
+
+${in_scope}
+
+### 제외
+
+${out_of_scope}
+
+## 4. 용어와 기준
+
+${terms_and_authorities}
+
+## 5. 요구사항
+
+### ${requirement_item_id} — ${requirement_item_title}
+
+${requirement_statement}
+
+**영향 범위**
+
+- 인터페이스: ${interfaces_or_none}
+- 영속성: ${persistence_or_none}
+- 후속 사용 주체: ${downstream_consumers_or_none}
+- 마이그레이션: ${migration_or_none}
+- 호환성: ${compatibility_or_none}
+- 배포 전제 조건: ${deployment_prerequisites_or_none}
+
+## 6. 제약과 불변조건
+
+${constraints_and_invariants}
+
+## 7. 인수 기준
+
+### ${acceptance_criterion_id} — ${acceptance_criterion_title}
+
+**판정 기준**
+
+${judgment}
+
+**검증**
+
+${verification}
+
+**검증 분류**
+
+- 수준: ${verification_level}
+- 백엔드: ${verification_backend_or_none}
+- 케이스: ${verification_cases}
+
+**상태 불변조건**
+
+${state_invariants}
+
+## 8. 오류 및 충돌 계약
+
+${error_and_conflict_contract}
+
+## 9. 데이터 및 인터페이스 계약
+
+${data_and_interface_contract}
+
+## 10. 하위 호환성
+
+${backward_compatibility}
+
+## 11. 추적성
+
+- 근거 이슈: ${source_issue_id}
+- 구현 PR: 미정
+- 관련 설계 문서: ${related_design_documents_or_none}
+- 관련 요구사항: ${related_requirements_or_none}

harness/docs/runtime-flow/README.md

@@ -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나 작성 안내 문구를 남기지 않는다.

harness/docs/runtime-flow/TEMPLATE.md

@@ -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}