# 하네스 v2

이 디렉터리는 규칙의 중립 원본, 플랫폼 어댑터, 결정론 실행기와 테스트를 소유한다. `raw/`와 `wiki/`는 지식 콘텐츠이며 하네스 구현의 원본이 아니다. 기존 플랫폼 경로는 호환 표면으로 유지하되 `harness/source/`에서만 생성한다.

## 디렉터리 책임

| 경로 | 책임 | 편집 정책 |
|---|---|---|
| `harness/source/` | workflow·agent·실행 프로필의 중립 원본 | 직접 편집 |
| `harness/adapters/` | Claude·Codex·Antigravity 표현 생성 | 생성기만 편집 |
| `harness/runtime/` | transaction·graph·MOC·proof·문체 검사 | 직접 편집 |
| `harness/tests/` | 고정 fixture와 회귀 테스트 | 직접 편집 |
| `.claude/`, `.codex/`, `.agents/` | 플랫폼 호환 산출물 | 직접 편집 금지, 생성기 사용 |
| `raw/`, `wiki/` | 현재 vault 호환 콘텐츠 | 문서 workflow로 편집 |
| `vault/` | project-first 점진 이관 경계 | `vault/README.md`의 이관 규칙 적용 |

한국어 사용자 용어의 기준은 `harness/source/terminology/ko.json`이다. frontmatter key·stable ID·status·failure code·CLI·path·정확한 기술명은 보존하고, 사용자 제목과 설명은 한국어 하나로 쓴다.

## 하네스 제어 흐름

질문: project Work Item에서 branch가 생성될 때 어떤 검사를 통과한 뒤 저장되는가?

```mermaid
sequenceDiagram
    autonumber
    actor User as 사용자
    participant Flow as 워크플로
    participant Packet as 계약 패킷
    participant Writer as 문서 작성기
    participant Gate as 결정론 검사
    participant Disk as 저장소

    User->>Flow: project + WI 요청
    Flow->>Packet: revision과 결정을 고정
    Packet->>Writer: branch 초안 전달
    Writer->>Gate: graph와 link 검사
    alt 모든 검사 통과
        Gate->>Disk: 원자적 반영
    else 검사 실패
        Gate-->>User: 실패 코드 반환
    end
```

핵심 결정은 검사가 끝난 파일만 한 transaction으로 교체한다는 점이다. `harness/runtime/branch_from_project.py`가 이 순서를 구현한다.

## 문서 수명주기

질문: 외부 근거가 공개 산출물로 이어질 때 어떤 기준 문서를 거치는가?

```mermaid
sequenceDiagram
    autonumber
    participant Source as 근거 자료
    participant Project as 프로젝트 계약
    participant Branch as 브랜치 계약
    participant Code as 구현 증거
    participant Wiki as 기준 지식
    participant Publish as 공개 문서

    Source->>Project: Claim을 뒷받침
    Project->>Branch: Decision을 상속
    Branch->>Code: 구현·검증 조건 지정
    Code-->>Branch: 증거 등급 반환
    Branch->>Wiki: 검증된 내용 승격
    Wiki->>Publish: 면접·블로그 파생
```

`raw/`에서 공개 문서로 바로 이동하는 경로는 없다. 공개 문서는 `reviewed` 이상의 `wiki/concepts/` 또는 `wiki/projects/`에서만 파생한다.

## 결정 소유권과 예외 승인

질문: branch가 project 결정을 다르게 적용하려면 어떤 절차가 필요한가?

```mermaid
sequenceDiagram
    autonumber
    participant Branch as 브랜치
    participant Graph as 그래프 검사기
    participant Project as 프로젝트 결정
    actor Owner as 승인자

    Branch->>Graph: inherited ref 제출
    Graph->>Project: revision·summary 대조
    alt 결정을 그대로 적용
        Project-->>Graph: 일치
        Graph-->>Branch: 진행 허용
    else 다른 동작 필요
        Branch->>Owner: 이유·영향 승인 요청
        Owner-->>Graph: 승인 ID 전달
        Graph-->>Branch: override 기록 후 허용
    end
```

프로젝트 불변식은 Project Decision이, 단일 branch 구현 선택은 Branch-local Decision이 소유한다. 차이는 `overrides`와 `Declared Overrides` 표 양쪽에 같은 revision과 승인 ID가 있을 때만 허용한다.

## Obsidian 연결 갱신

질문: 자식의 Parent 한 곳만 편집해도 부모 MOC가 어떻게 맞춰지는가?

```mermaid
sequenceDiagram
    autonumber
    actor Editor as 작성자
    participant Child as 자식 frontmatter
    participant Indexer as MOC 생성기
    participant Parent as 부모 generated block
    participant Graph as 그래프 검사기
    participant Disk as 저장소

    Editor->>Child: project·parent 저장
    Child->>Indexer: 기준 edge 제공
    Indexer->>Parent: 자식 목록 재생성
    Parent->>Graph: reverse view 검사
    alt edge 일치
        Graph->>Disk: 함께 반영
    else edge 불일치
        Graph-->>Editor: MISSING_EXPECTED_EDGE
    end
```

자식의 `project`와 `parent_branch`가 정방향 기준이다. 부모의 generated block은 `harness/runtime/moc_indexer.py`가 만들며 사람이 수정하지 않는다.

## 실행 명령

```bash
python3 harness/adapters/generate.py --check
python3 harness/adapters/generate_rules.py --check
python3 harness/runtime/source_hygiene.py --check
python3 harness/runtime/branch_from_project.py --help
python3 harness/runtime/execution_profile.py --workflow branch-spec
python3 harness/runtime/fix_bare_refs.py --check
python3 harness/runtime/moc_indexer.py --check
python3 harness/runtime/layout_check.py
python3 .claude/hooks/wiki_graph_contract_check.py --all
python3 -m unittest discover -s harness/tests -p 'test_*.py' -v
```

## 다이어그램 자체 점검

- [x] 각 다이어그램은 하나의 질문만 다룬다.
- [x] participant는 4~6개이고 메시지는 5~6개다.
- [x] 라벨은 두 줄을 넘지 않는다.
- [x] 메시지 라벨은 다섯 단어 이내다.
- [x] 색과 범례를 추가하지 않았다.
- [x] 장식용 boundary가 없다.
- [x] 진입점은 actor 또는 첫 participant로 분명하다.
- [x] 세부 책임과 구현 경로는 본문 표와 설명에 분리했다.