init: llm-wiki-haness 하네스 설계

2026-07-24 14:21:35 +09:00
parent 42bf3db4fd
commit 6c53ded9cb
2436 changed files with 194486 additions and 1 deletions
@@ -0,0 +1,147 @@
+# 하네스 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] 세부 책임과 구현 경로는 본문 표와 설명에 분리했다.