init: readme 작성 하네스 설계

2026-07-24 13:26:18 +09:00
parent 7fb4217f7c
commit c708cbcf9a
317 changed files with 24223 additions and 1 deletions
@@ -0,0 +1,211 @@
+# README Harness
+
+<!-- readme-harness:metadata owner=readme-harness -->
+
+저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.
+<!-- claim-id: C-PROJECT-001 -->
+
+명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.
+<!-- claim-id: C-OUTPUT-001 -->
+
+현재 지원하는 작성·검증 흐름은 Codex용입니다. <!-- claim-id: C-CODEX-001 -->
+
+Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.
+<!-- claim-id: C-XTOOL-001 -->
+
+<!-- readme-harness:start overview -->
+<!-- section-id: overview -->
+## 무엇을 만드는가
+
+README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+- 새 README 작성
+- 기존 README 점검
+- 사람 작성 내용을 보존한 갱신
+- 특정 섹션만 다시 작성
+- 검토한 패치만 직접 적용
+
+<!-- readme-harness:end overview -->
+
+<!-- readme-harness:start proof -->
+<!-- section-id: proof -->
+## 실제 결과
+
+아래 내용은 검토를 통과한 이전 실행의 패치 일부입니다.
+<!-- claim-id: C-PROOF-001 -->
+
+```diff
+-A GitHub-README-specialized harness built around a shared core with entrypoints
+-for **Codex**, **Antigravity**, and **Claude**. It does not "prettify" READMEs —
+-it analyzes the facts that exist in a repository, judges project type and
+-audience, then iteratively produces and maintains a README with a readable
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
+```
+
+<!-- visual-id: reviewed-patch-preview -->
+
+[전체 패치와 출처](examples/readme-showcase/README.patch)에서 더 긴 변경 내용을 확인할 수 있습니다.
+
+<!-- readme-harness:end proof -->
+
+<!-- readme-harness:start quick-start -->
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.
+<!-- claim-id: C-INVOCATION-001 -->
+
+<!-- quick-start-step: invocation -->
+Codex에 다음과 같이 요청합니다.
+
+> 이 저장소의 README를 `bootstrap` 모드로 작성해 주세요.
+> 주 독자는 백엔드 개발자이며, 설치와 첫 실행 방법을 우선해 주세요.
+
+<!-- quick-start-step: expected-result -->
+작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.
+<!-- claim-id: C-RESULTS-001 -->
+
+<!-- quick-start-step: success-check -->
+생성된 README의 명령과 링크를 읽고, 패치가 의도한 범위만 바꾸는지 검토합니다.
+
+대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.
+<!-- claim-id: C-NO-AUTO-APPLY-001 -->
+
+<!-- quick-start-step: apply -->
+검토가 끝난 패치만 직접 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+```
+
+적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.
+<!-- claim-id: C-APPLY-CHECK-001 -->
+
+<!-- readme-harness:end quick-start -->
+
+<!-- readme-harness:start usage -->
+<!-- section-id: usage -->
+## 어떤 작업을 지원하는가
+
+새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.
+<!-- claim-id: C-MODE-BOOTSTRAP-001 -->
+
+현재 README의 문제만 찾는 작업은 `audit`입니다.
+<!-- claim-id: C-MODE-AUDIT-001 -->
+
+사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.
+<!-- claim-id: C-MODE-REFRESH-001 -->
+
+한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.
+<!-- claim-id: C-MODE-SECTION-001 -->
+
+<!-- readme-harness:end usage -->
+
+<!-- readme-harness:start safeguards -->
+<!-- section-id: safeguards -->
+## 안전하게 다루는 방법
+
+코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.
+<!-- claim-id: C-SOURCE-SPLIT-001 -->
+
+명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.
+<!-- claim-id: C-FACT-TRACE-001 -->
+
+갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.
+<!-- claim-id: C-PRESERVE-001 -->
+
+사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.
+<!-- claim-id: C-CONFLICT-001 -->
+
+비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.
+<!-- claim-id: C-SECRET-PATH-001 -->
+
+검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.
+<!-- claim-id: C-STALE-001 -->
+
+<!-- readme-harness:end safeguards -->
+
+<!-- readme-harness:start workflow -->
+<!-- section-id: workflow -->
+## 동작 방식
+
+사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용
+<!-- claim-id: C-WORKFLOW-001 -->
+
+검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.
+<!-- claim-id: C-REWORK-001 -->
+
+<!-- readme-harness:end workflow -->
+
+<!-- readme-harness:start inputs -->
+<!-- section-id: inputs -->
+## 입력과 생성 파일
+
+`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.
+<!-- claim-id: C-REQUEST-001 -->
+
+사용자는 다음 두 결과를 주로 확인합니다.
+
+- `README.generated.md`: 생성된 README
+- `README.patch`: 현재 README와의 차이
+
+각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.
+<!-- claim-id: C-RUN-DIR-001 -->
+
+<!-- readme-harness:end inputs -->
+
+<!-- readme-harness:start development -->
+<!-- section-id: development -->
+## 개발
+
+개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.
+<!-- claim-id: C-DEV-PREREQ-001 -->
+
+저장소 루트에서 개발 모드로 설치합니다.
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+전체 테스트는 다음 명령으로 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+<!-- readme-harness:end development -->
+
+<!-- readme-harness:start documentation -->
+<!-- section-id: documentation -->
+## 상세 문서
+
+- [구성요소와 책임](docs/architecture.md)
+- [시각 자료와 실제 결과 증명](docs/visuals.md)
+- [모드별 처리 단계와 차단 조건](docs/state-machine.md)
+- [모델 사용량 기록](docs/usage-metrics.md)
+- [블라인드 README 품질 비교](docs/quality-benchmark.md)
+- [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.
+<!-- claim-id: C-LAYOUT-001 -->
+
+<!-- readme-harness:end documentation -->
+
+<!-- readme-harness:start limitations -->
+<!-- section-id: limitations -->
+## 현재 한계
+
+- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.
+  <!-- claim-id: C-WRITING-LIMIT-001 -->
+
+- 실행 기록이 없는 명령은 정적으로만 확인합니다.
+  <!-- claim-id: C-VERIFY-LIMIT-001 -->
+
+- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.
+  <!-- claim-id: C-XTOOL-LIMIT-001 -->
+
+- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다.
+  <!-- claim-id: C-BENCH-LIMIT-001 -->
+
+<!-- readme-harness:end limitations -->
@@ -0,0 +1,211 @@
+# README Harness
+
+<!-- readme-harness:metadata owner=readme-harness -->
+
+저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.
+<!-- claim-id: C-PROJECT-001 -->
+
+명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.
+<!-- claim-id: C-OUTPUT-001 -->
+
+현재 지원하는 작성·검증 흐름은 Codex용입니다. <!-- claim-id: C-CODEX-001 -->
+
+Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.
+<!-- claim-id: C-XTOOL-001 -->
+
+<!-- readme-harness:start overview -->
+<!-- section-id: overview -->
+## 무엇을 만드는가
+
+README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+- 새 README 작성
+- 기존 README 점검
+- 사람 작성 내용을 보존한 갱신
+- 특정 섹션만 다시 작성
+- 검토한 패치만 직접 적용
+
+<!-- readme-harness:end overview -->
+
+<!-- readme-harness:start proof -->
+<!-- section-id: proof -->
+## 실제 결과
+
+아래 내용은 검토를 통과한 이전 실행의 패치 일부입니다.
+<!-- claim-id: C-PROOF-001 -->
+
+```diff
+-A GitHub-README-specialized harness built around a shared core with entrypoints
+-for **Codex**, **Antigravity**, and **Claude**. It does not "prettify" READMEs —
+-it analyzes the facts that exist in a repository, judges project type and
+-audience, then iteratively produces and maintains a README with a readable
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
+```
+
+<!-- visual-id: reviewed-patch-preview -->
+
+[전체 패치와 출처](examples/readme-showcase/README.patch)에서 더 긴 변경 내용을 확인할 수 있습니다.
+
+<!-- readme-harness:end proof -->
+
+<!-- readme-harness:start quick-start -->
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.
+<!-- claim-id: C-INVOCATION-001 -->
+
+<!-- quick-start-step: invocation -->
+Codex에 다음과 같이 요청합니다.
+
+> 이 저장소의 README를 `bootstrap` 모드로 작성해 주세요.
+> 주 독자는 백엔드 개발자이며, 설치와 첫 실행 방법을 우선해 주세요.
+
+<!-- quick-start-step: expected-result -->
+작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.
+<!-- claim-id: C-RESULTS-001 -->
+
+<!-- quick-start-step: success-check -->
+생성된 README의 명령과 링크를 읽고, 패치가 의도한 범위만 바꾸는지 검토합니다.
+
+대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.
+<!-- claim-id: C-NO-AUTO-APPLY-001 -->
+
+<!-- quick-start-step: apply -->
+검토가 끝난 패치만 직접 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+```
+
+적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.
+<!-- claim-id: C-APPLY-CHECK-001 -->
+
+<!-- readme-harness:end quick-start -->
+
+<!-- readme-harness:start usage -->
+<!-- section-id: usage -->
+## 어떤 작업을 지원하는가
+
+새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.
+<!-- claim-id: C-MODE-BOOTSTRAP-001 -->
+
+현재 README의 문제만 찾는 작업은 `audit`입니다.
+<!-- claim-id: C-MODE-AUDIT-001 -->
+
+사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.
+<!-- claim-id: C-MODE-REFRESH-001 -->
+
+한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.
+<!-- claim-id: C-MODE-SECTION-001 -->
+
+<!-- readme-harness:end usage -->
+
+<!-- readme-harness:start safeguards -->
+<!-- section-id: safeguards -->
+## 안전하게 다루는 방법
+
+코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.
+<!-- claim-id: C-SOURCE-SPLIT-001 -->
+
+명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.
+<!-- claim-id: C-FACT-TRACE-001 -->
+
+갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.
+<!-- claim-id: C-PRESERVE-001 -->
+
+사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.
+<!-- claim-id: C-CONFLICT-001 -->
+
+비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.
+<!-- claim-id: C-SECRET-PATH-001 -->
+
+검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.
+<!-- claim-id: C-STALE-001 -->
+
+<!-- readme-harness:end safeguards -->
+
+<!-- readme-harness:start workflow -->
+<!-- section-id: workflow -->
+## 동작 방식
+
+사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용
+<!-- claim-id: C-WORKFLOW-001 -->
+
+검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.
+<!-- claim-id: C-REWORK-001 -->
+
+<!-- readme-harness:end workflow -->
+
+<!-- readme-harness:start inputs -->
+<!-- section-id: inputs -->
+## 입력과 생성 파일
+
+`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.
+<!-- claim-id: C-REQUEST-001 -->
+
+사용자는 다음 두 결과를 주로 확인합니다.
+
+- `README.generated.md`: 생성된 README
+- `README.patch`: 현재 README와의 차이
+
+각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.
+<!-- claim-id: C-RUN-DIR-001 -->
+
+<!-- readme-harness:end inputs -->
+
+<!-- readme-harness:start development -->
+<!-- section-id: development -->
+## 개발
+
+개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.
+<!-- claim-id: C-DEV-PREREQ-001 -->
+
+저장소 루트에서 개발 모드로 설치합니다.
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+전체 테스트는 다음 명령으로 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+<!-- readme-harness:end development -->
+
+<!-- readme-harness:start documentation -->
+<!-- section-id: documentation -->
+## 상세 문서
+
+- [구성요소와 책임](docs/architecture.md)
+- [시각 자료와 실제 결과 증명](docs/visuals.md)
+- [모드별 처리 단계와 차단 조건](docs/state-machine.md)
+- [모델 사용량 기록](docs/usage-metrics.md)
+- [블라인드 README 품질 비교](docs/quality-benchmark.md)
+- [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.
+<!-- claim-id: C-LAYOUT-001 -->
+
+<!-- readme-harness:end documentation -->
+
+<!-- readme-harness:start limitations -->
+<!-- section-id: limitations -->
+## 현재 한계
+
+- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.
+  <!-- claim-id: C-WRITING-LIMIT-001 -->
+
+- 실행 기록이 없는 명령은 정적으로만 확인합니다.
+  <!-- claim-id: C-VERIFY-LIMIT-001 -->
+
+- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.
+  <!-- claim-id: C-XTOOL-LIMIT-001 -->
+
+- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다.
+  <!-- claim-id: C-BENCH-LIMIT-001 -->
+
+<!-- readme-harness:end limitations -->
@@ -0,0 +1,413 @@
+--- README.md (current)
+++ README.md (candidate)
+@@ -1,224 +1,211 @@
+ # README Harness
+ 
+-이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+-명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다. <!-- claim-id: C-PROJECT-001 -->
+-
+-- 새 README 작성
+-- 기존 문서 점검
+-- 사람 작성 영역을 보존한 갱신
+-- 특정 섹션과 관련 검증 산출물의 재생성
+-- 검토 후 별도로 실행하는 적용
+-
+<!-- readme-harness:metadata owner=readme-harness -->
+
+저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.
+<!-- claim-id: C-PROJECT-001 -->
+
+명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.
+<!-- claim-id: C-OUTPUT-001 -->
+
+현재 지원하는 작성·검증 흐름은 Codex용입니다. <!-- claim-id: C-CODEX-001 -->
+
+Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.
+<!-- claim-id: C-XTOOL-001 -->
+
+<!-- readme-harness:start overview -->
+ <!-- section-id: overview -->
+ ## 무엇을 만드는가
+ 
+ README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+ 
+-`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다. <!-- claim-id: C-MODE-001 -->
+-
+-저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을
+-넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인
+-근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.
+-<!-- claim-id: C-SAFETY-SUMMARY-001 -->
+-
+-결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며,
+-다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
+-<!-- claim-id: C-LIMIT-001 -->
+-
+-<!-- section-id: installation -->
+-## 설치
+-
+-`Python` 3.12 이상이 필요합니다.
+-런타임 의존성은 `jsonschema`와 `PyYAML`입니다.
+-개발 의존성은 `pytest`입니다. <!-- claim-id: C-RUNTIME-001 -->
+-
+-저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다.
+- 새 README 작성
+- 기존 README 점검
+- 사람 작성 내용을 보존한 갱신
+- 특정 섹션만 다시 작성
+- 검토한 패치만 직접 적용
+
+<!-- readme-harness:end overview -->
+
+<!-- readme-harness:start proof -->
+<!-- section-id: proof -->
+## 실제 결과
+
+아래 내용은 검토를 통과한 이전 실행의 패치 일부입니다.
+<!-- claim-id: C-PROOF-001 -->
+
+```diff
+-A GitHub-README-specialized harness built around a shared core with entrypoints
+-for **Codex**, **Antigravity**, and **Claude**. It does not "prettify" READMEs —
+-it analyzes the facts that exist in a repository, judges project type and
+-audience, then iteratively produces and maintains a README with a readable
++이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
++명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
+```
+
+<!-- visual-id: reviewed-patch-preview -->
+
+[전체 패치와 출처](examples/readme-showcase/README.patch)에서 더 긴 변경 내용을 확인할 수 있습니다.
+
+<!-- readme-harness:end proof -->
+
+<!-- readme-harness:start quick-start -->
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.
+<!-- claim-id: C-INVOCATION-001 -->
+
+<!-- quick-start-step: invocation -->
+Codex에 다음과 같이 요청합니다.
+
+> 이 저장소의 README를 `bootstrap` 모드로 작성해 주세요.
+> 주 독자는 백엔드 개발자이며, 설치와 첫 실행 방법을 우선해 주세요.
+
+<!-- quick-start-step: expected-result -->
+작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.
+<!-- claim-id: C-RESULTS-001 -->
+
+<!-- quick-start-step: success-check -->
+생성된 README의 명령과 링크를 읽고, 패치가 의도한 범위만 바꾸는지 검토합니다.
+
+대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.
+<!-- claim-id: C-NO-AUTO-APPLY-001 -->
+
+<!-- quick-start-step: apply -->
+검토가 끝난 패치만 직접 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+```
+
+적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.
+<!-- claim-id: C-APPLY-CHECK-001 -->
+
+<!-- readme-harness:end quick-start -->
+
+<!-- readme-harness:start usage -->
+<!-- section-id: usage -->
+## 어떤 작업을 지원하는가
+
+새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.
+<!-- claim-id: C-MODE-BOOTSTRAP-001 -->
+
+현재 README의 문제만 찾는 작업은 `audit`입니다.
+<!-- claim-id: C-MODE-AUDIT-001 -->
+
+사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.
+<!-- claim-id: C-MODE-REFRESH-001 -->
+
+한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.
+<!-- claim-id: C-MODE-SECTION-001 -->
+
+<!-- readme-harness:end usage -->
+
+<!-- readme-harness:start safeguards -->
+<!-- section-id: safeguards -->
+## 안전하게 다루는 방법
+
+코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.
+<!-- claim-id: C-SOURCE-SPLIT-001 -->
+
+명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.
+<!-- claim-id: C-FACT-TRACE-001 -->
+
+갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.
+<!-- claim-id: C-PRESERVE-001 -->
+
+사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.
+<!-- claim-id: C-CONFLICT-001 -->
+
+비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.
+<!-- claim-id: C-SECRET-PATH-001 -->
+
+검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.
+<!-- claim-id: C-STALE-001 -->
+
+<!-- readme-harness:end safeguards -->
+
+<!-- readme-harness:start workflow -->
+<!-- section-id: workflow -->
+## 동작 방식
+
+사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용
+<!-- claim-id: C-WORKFLOW-001 -->
+
+검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.
+<!-- claim-id: C-REWORK-001 -->
+
+<!-- readme-harness:end workflow -->
+
+<!-- readme-harness:start inputs -->
+<!-- section-id: inputs -->
+## 입력과 생성 파일
+
+`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.
+<!-- claim-id: C-REQUEST-001 -->
+
+사용자는 다음 두 결과를 주로 확인합니다.
+
+- `README.generated.md`: 생성된 README
+- `README.patch`: 현재 README와의 차이
+
+각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.
+<!-- claim-id: C-RUN-DIR-001 -->
+
+<!-- readme-harness:end inputs -->
+
+<!-- readme-harness:start development -->
+<!-- section-id: development -->
+## 개발
+
+개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.
+<!-- claim-id: C-DEV-PREREQ-001 -->
+
+저장소 루트에서 개발 모드로 설치합니다.
+ 
+ ```bash
+ python3 -m pip install -e ".[dev]"
+ ```
+ 
+-이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지
+-실행해 증명하지 않았습니다. <!-- claim-id: C-INSTALL-001 -->
+-
+-<!-- section-id: quick-start -->
+-## 빠른 시작
+-
+-먼저 전체 테스트를 실행합니다.
+전체 테스트는 다음 명령으로 실행합니다.
+ 
+ ```bash
+ python3 -m pytest -q
+ ```
+ 
+-종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재
+-README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다.
+-
+-자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새
+-가상환경의 동일한 결과까지 보장하는 계약은 아닙니다. <!-- claim-id: C-TEST-COMMAND-001 -->
+-
+-이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서
+-`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성
+-역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사
+-산출물을 준비합니다. <!-- claim-id: C-AUTHORING-001 -->
+-
+-대상 저장소용 실행 디렉터리를 만듭니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
+-```
+-
+-이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.
+-<!-- claim-id: C-INIT-001 -->
+-
+-실행 디렉터리에 `readme-request.yaml`, `repository-facts.yaml`, `readme-brief.yaml`,
+-`readme-outline.yaml`, `README.candidate.md`, `claim-map.yaml`, `visual-plan.yaml`,
+-`review-findings.yaml`이 준비되면 모든 결정론적 게이트를 재생합니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
+-```
+-
+-드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 `QUALITY_REVIEWED`까지
+-검증합니다. <!-- claim-id: C-BOOTSTRAP-001 -->
+-
+-<!-- section-id: usage -->
+-## 사용 모드
+-
+-| 작업 | 모드 | 결과 |
+-|---|---|---|
+-| README가 없거나 전면 재작성 | `bootstrap` | 검증된 후보와 적용 준비용 패치 |
+-| 기존 문서의 결함만 점검 | `audit` | 감사 결과와 검증 보고서, 후보·패치 없음 |
+-| 사람 작성 영역을 보존한 갱신 | `refresh` | 3방향 병합과 병합본 전체 재검증 |
+-| 한 섹션과 파급 산출물 갱신 | `section-update` | 관련 산출물 무효화 후 갱신 검증 재실행 |
+-
+-네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어
+-있습니다. <!-- claim-id: C-USAGE-001 -->
+-
+-<!-- section-id: api -->
+-## 요청 API, 설정과 산출물
+-
+-`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을
+-정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은
+-`runs/<repo-id>/<run-id>` 아래에서 격리합니다. <!-- claim-id: C-INPUT-001 -->
+-
+-어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지
+-않은 값은 0으로 추정하지 않습니다. <!-- claim-id: C-USAGE-METRICS-001 -->
+-
+-대표 산출물은 다음 순서로 이어집니다.
+-
+-```text
+-readme-brief.yaml + readme-outline.yaml
+-README.candidate.md + claim-map.yaml + visual-plan.yaml
+-prose-report.json + verification.json + review-findings.yaml
+-quality-manifest.yaml
+-README.generated.md + README.patch + apply-manifest.yaml
+-```
+-
+-품질 검토를 통과한 뒤 다음 명령으로 패치를 준비합니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
+-```
+-
+-이 단계는 `README.generated.md`, `README.patch`, `apply-manifest.yaml`을 만들고
+-상태를 `READY_FOR_APPLY`로 전진시킵니다. <!-- claim-id: C-PREPARE-001 -->
+-
+-검토가 끝난 패치만 별도 명령으로 적용합니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
+-```
+-
+-적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
+-<!-- claim-id: C-APPLY-001 -->
+-
+-<!-- section-id: architecture -->
+-## 동작 방식
+-
+-사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는
+-근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적
+-게이트와 독립 품질 심사를 통과해야 패치가 됩니다. <!-- claim-id: C-FLOW-001 -->
+-
+-```mermaid
+-flowchart LR
+-    T[Codex / Claude / Antigravity] --> O[실행 조정]
+-    U[사용자 요구] --> P[독자 흐름·용어·그림 결정]
+-    R[대상 저장소] --> E[근거 수집·프로젝트 분류]
+-    O --> E
+-    O --> P
+-    E --> P
+-    P --> W[README 작성]
+-    P --> V[그림 소스·자산 생성]
+-    W --> G[근거·명령·경로·문체 검사]
+-    V --> G
+-    G --> Q[독립 품질 심사]
+-    Q -->|수정 필요| P
+-    Q -->|통과| A[패치 준비·명시적 적용]
+-    H[(해시 기반 실행 산출물)] --- E
+-    H --- P
+-    H --- G
+-    H --- A
+-```
+-
+-<!-- visual-id: harness-flow -->
+-
+-구성요소 책임과 컨텍스트 경계는 [아키텍처 문서](docs/architecture.md)에,
+-모드별 전이는 [상태기계 문서](docs/state-machine.md)에 정리했습니다.
+-
+-<!-- section-id: safeguards -->
+-## 안전장치
+-
+-- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.
+-- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을
+-  차단합니다. <!-- claim-id: C-TERM-001 -->
+-- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이
+-  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->
+-- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,
+-  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->
+-- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로
+-  전진합니다. <!-- claim-id: C-AUDIT-001 -->
+-- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새
+-  후보가 충돌하면 자동 적용을 막습니다. <!-- claim-id: C-MERGE-001 -->
+-- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나
+-  적용을 차단합니다. <!-- claim-id: C-APPLY-SAFETY-001 -->
+-
+-시각 자료의 소스·자산·대체 텍스트·신선도 규칙은
+-[시각 자료 정책](docs/visuals.md)에서 확인할 수 있습니다.
+-
+-<!-- section-id: tests -->
+-## 테스트
+-
+-전체 회귀 테스트는 다음 명령으로 실행합니다.
+-
+-```bash
+-python3 -m pytest -q
+-```
+-
+-GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은
+-Python 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행
+-경로, Mermaid 그림 결정을 확인합니다. <!-- claim-id: C-CI-001 -->
+-
+<!-- readme-harness:end development -->
+
+<!-- readme-harness:start documentation -->
+ <!-- section-id: documentation -->
+ ## 상세 문서
+ 
+-- [구성요소와 컨텍스트 경계](docs/architecture.md)
+-- [그림 결정과 소스·자산 계약](docs/visuals.md)
+-- [모드별 상태와 차단 조건](docs/state-machine.md)
+-- [모델 사용량 계측](docs/usage-metrics.md)
+-- [블라인드 README 품질 벤치마크](docs/quality-benchmark.md)
+- [구성요소와 책임](docs/architecture.md)
+- [시각 자료와 실제 결과 증명](docs/visuals.md)
+- [모드별 처리 단계와 차단 조건](docs/state-machine.md)
+- [모델 사용량 기록](docs/usage-metrics.md)
+- [블라인드 README 품질 비교](docs/quality-benchmark.md)
+ - [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+ 
+-주요 구현은 `src/readme_harness`, 스키마·규칙·워크플로는 `.agents`, 테스트는
+-`tests`에 있습니다. <!-- claim-id: C-LAYOUT-001 -->
+-
+주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.
+<!-- claim-id: C-LAYOUT-001 -->
+
+<!-- readme-harness:end documentation -->
+
+<!-- readme-harness:start limitations -->
+ <!-- section-id: limitations -->
+ ## 현재 한계
+ 
+-- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된
+-  산출물을 검증하고 상태를 전진시킵니다.
+-- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증
+-  목표입니다. <!-- claim-id: C-LIMIT-002 -->
+-- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은
+-  명령은 실제 실행 성공을 뜻하지 않습니다. <!-- claim-id: C-VERIFY-LIMIT-001 -->
+-- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다.
+-  `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다. <!-- claim-id: C-BENCH-LIMIT-001 -->
+- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.
+  <!-- claim-id: C-WRITING-LIMIT-001 -->
+
+- 실행 기록이 없는 명령은 정적으로만 확인합니다.
+  <!-- claim-id: C-VERIFY-LIMIT-001 -->
+
+- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.
+  <!-- claim-id: C-XTOOL-LIMIT-001 -->
+
+- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다.
+  <!-- claim-id: C-BENCH-LIMIT-001 -->
+
+<!-- readme-harness:end limitations -->
@@ -0,0 +1,7 @@
+schema-version: 1
+mode: bootstrap
+target-rel: README.md
+generated-hash: sha256:b54317f98e0bea64cc31f489caca9a541b24bbdfec3aab6af3be41d0dd4dab22
+target-before-hash: sha256:dd241b6b8b7a0972086226c73b217128d98224cf30ab87505a6d5e8e0d2dcedf
+repository-snapshot-hash: sha256:2ff902bd9a7de01648f972d099614584bc26fa84c1492cec61dc6da82e4f6275
+review-score: 90
@@ -0,0 +1,211 @@
+# README Harness
+
+<!-- readme-harness:metadata owner=readme-harness -->
+
+저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.
+<!-- claim-id: C-PROJECT-001 -->
+
+명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.
+<!-- claim-id: C-OUTPUT-001 -->
+
+현재 지원하는 작성·검증 흐름은 Codex용입니다. <!-- claim-id: C-CODEX-001 -->
+
+Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.
+<!-- claim-id: C-XTOOL-001 -->
+
+<!-- readme-harness:start overview -->
+<!-- section-id: overview -->
+## 무엇을 만드는가
+
+README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+- 새 README 작성
+- 기존 README 점검
+- 사람 작성 내용을 보존한 갱신
+- 특정 섹션만 다시 작성
+- 검토한 패치만 직접 적용
+
+<!-- readme-harness:end overview -->
+
+<!-- readme-harness:start proof -->
+<!-- section-id: proof -->
+## 실제 결과
+
+아래 내용은 검토와 적용을 마친 이전 실행의 패치 일부입니다.
+<!-- claim-id: C-PROOF-001 -->
+
+```diff
+-A GitHub-README-specialized harness built around a shared core with entrypoints
+-for **Codex**, **Antigravity**, and **Claude**. It does not "prettify" READMEs —
+-it analyzes the facts that exist in a repository, judges project type and
+-audience, then iteratively produces and maintains a README with a readable
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
+```
+
+<!-- visual-id: reviewed-patch-preview -->
+
+[전체 패치와 출처](examples/readme-showcase/README.patch)에서 더 긴 변경 내용을 확인할 수 있습니다.
+
+<!-- readme-harness:end proof -->
+
+<!-- readme-harness:start quick-start -->
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.
+<!-- claim-id: C-INVOCATION-001 -->
+
+<!-- quick-start-step: invocation -->
+Codex에 다음과 같이 요청합니다.
+
+> 이 저장소의 README를 `bootstrap` 모드로 작성해 주세요.
+> 주 독자는 백엔드 개발자이며, 설치와 첫 실행 방법을 우선해 주세요.
+
+<!-- quick-start-step: expected-result -->
+작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.
+<!-- claim-id: C-RESULTS-001 -->
+
+<!-- quick-start-step: success-check -->
+생성된 README의 명령과 링크를 읽고, 패치가 의도한 범위만 바꾸는지 검토합니다.
+
+대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.
+<!-- claim-id: C-NO-AUTO-APPLY-001 -->
+
+<!-- quick-start-step: apply -->
+검토가 끝난 패치만 직접 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+```
+
+적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.
+<!-- claim-id: C-APPLY-CHECK-001 -->
+
+<!-- readme-harness:end quick-start -->
+
+<!-- readme-harness:start usage -->
+<!-- section-id: usage -->
+## 어떤 작업을 지원하는가
+
+새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.
+<!-- claim-id: C-MODE-BOOTSTRAP-001 -->
+
+현재 README의 문제만 찾는 작업은 `audit`입니다.
+<!-- claim-id: C-MODE-AUDIT-001 -->
+
+사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.
+<!-- claim-id: C-MODE-REFRESH-001 -->
+
+한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.
+<!-- claim-id: C-MODE-SECTION-001 -->
+
+<!-- readme-harness:end usage -->
+
+<!-- readme-harness:start safeguards -->
+<!-- section-id: safeguards -->
+## 안전하게 다루는 방법
+
+코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.
+<!-- claim-id: C-SOURCE-SPLIT-001 -->
+
+명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.
+<!-- claim-id: C-FACT-TRACE-001 -->
+
+갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.
+<!-- claim-id: C-PRESERVE-001 -->
+
+사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.
+<!-- claim-id: C-CONFLICT-001 -->
+
+비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.
+<!-- claim-id: C-SECRET-PATH-001 -->
+
+검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.
+<!-- claim-id: C-STALE-001 -->
+
+<!-- readme-harness:end safeguards -->
+
+<!-- readme-harness:start workflow -->
+<!-- section-id: workflow -->
+## 동작 방식
+
+사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용
+<!-- claim-id: C-WORKFLOW-001 -->
+
+검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.
+<!-- claim-id: C-REWORK-001 -->
+
+<!-- readme-harness:end workflow -->
+
+<!-- readme-harness:start inputs -->
+<!-- section-id: inputs -->
+## 입력과 생성 파일
+
+`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.
+<!-- claim-id: C-REQUEST-001 -->
+
+사용자는 다음 두 결과를 주로 확인합니다.
+
+- `README.generated.md`: 생성된 README
+- `README.patch`: 현재 README와의 차이
+
+각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.
+<!-- claim-id: C-RUN-DIR-001 -->
+
+<!-- readme-harness:end inputs -->
+
+<!-- readme-harness:start development -->
+<!-- section-id: development -->
+## 개발
+
+개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.
+<!-- claim-id: C-DEV-PREREQ-001 -->
+
+저장소 루트에서 개발 모드로 설치합니다.
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+전체 테스트는 다음 명령으로 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+<!-- readme-harness:end development -->
+
+<!-- readme-harness:start documentation -->
+<!-- section-id: documentation -->
+## 상세 문서
+
+- [구성요소와 책임](docs/architecture.md)
+- [시각 자료와 실제 결과 증명](docs/visuals.md)
+- [모드별 처리 단계와 차단 조건](docs/state-machine.md)
+- [모델 사용량 기록](docs/usage-metrics.md)
+- [블라인드 README 품질 비교](docs/quality-benchmark.md)
+- [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.
+<!-- claim-id: C-LAYOUT-001 -->
+
+<!-- readme-harness:end documentation -->
+
+<!-- readme-harness:start limitations -->
+<!-- section-id: limitations -->
+## 현재 한계
+
+- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.
+  <!-- claim-id: C-WRITING-LIMIT-001 -->
+
+- 실행 기록이 없는 명령은 정적으로만 확인합니다.
+  <!-- claim-id: C-VERIFY-LIMIT-001 -->
+
+- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.
+  <!-- claim-id: C-XTOOL-LIMIT-001 -->
+
+- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다.
+  <!-- claim-id: C-BENCH-LIMIT-001 -->
+
+<!-- readme-harness:end limitations -->
@@ -0,0 +1,147 @@
+schema-version: 1
+claims:
+  - id: C-PROJECT-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-PROJECT-001}]
+    status: supported
+  - id: C-OUTPUT-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-VERIFY-001}, {fact-id: F-OUTPUT-001}]
+    status: supported
+  - id: C-CODEX-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-XTOOL-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-PROOF-001
+    type: factual
+    section: proof
+    sources: [{fact-id: F-PROOF-001}]
+    status: supported
+  - id: C-INVOCATION-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-RESULTS-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-OUTPUT-001}]
+    status: supported
+  - id: C-NO-AUTO-APPLY-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-APPLY-CHECK-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-MODE-BOOTSTRAP-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-OUTPUT-001}]
+    status: supported
+  - id: C-MODE-AUDIT-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-AUDIT-001}]
+    status: supported
+  - id: C-MODE-REFRESH-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-REFRESH-001}]
+    status: supported
+  - id: C-MODE-SECTION-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-SECTION-001}]
+    status: supported
+  - id: C-SOURCE-SPLIT-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-AUTHORITY-001}]
+    status: supported
+  - id: C-FACT-TRACE-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-CLAIM-001}, {fact-id: F-VERIFY-001}]
+    status: supported
+  - id: C-PRESERVE-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-REFRESH-001}]
+    status: supported
+  - id: C-CONFLICT-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-REFRESH-001}]
+    status: supported
+  - id: C-SECRET-PATH-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-SAFETY-001}]
+    status: supported
+  - id: C-STALE-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-SAFETY-001}, {fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-WORKFLOW-001
+    type: factual
+    section: workflow
+    sources: [{fact-id: F-WORKFLOW-001}]
+    status: supported
+  - id: C-REWORK-001
+    type: factual
+    section: workflow
+    sources: [{fact-id: F-WORKFLOW-001}]
+    status: supported
+  - id: C-REQUEST-001
+    type: factual
+    section: inputs
+    sources: [{fact-id: F-AUTHORITY-001}, {fact-id: F-REPO-LAYOUT-001}]
+    status: supported
+  - id: C-RUN-DIR-001
+    type: factual
+    section: inputs
+    sources: [{fact-id: F-RUN-LAYOUT-001}]
+    status: supported
+  - id: C-DEV-PREREQ-001
+    type: factual
+    section: development
+    sources: [{fact-id: F-RUNTIME-001}]
+    status: supported
+  - id: C-LAYOUT-001
+    type: factual
+    section: documentation
+    sources: [{fact-id: F-REPO-LAYOUT-001}]
+    status: supported
+  - id: C-WRITING-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-VERIFY-001}]
+    status: supported
+  - id: C-VERIFY-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-VERIFY-001}]
+    status: supported
+  - id: C-XTOOL-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-BENCH-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-BENCH-001}]
+    status: supported
@@ -0,0 +1,16 @@
+{
+  "schema-version": 1,
+  "policy-id": "korean-reader-prose-v1",
+  "language": "ko-KR",
+  "applicable": true,
+  "scope": "candidate",
+  "state": "PASS",
+  "summary": {
+    "errors": 0,
+    "warnings": 0,
+    "sentences": 52,
+    "prose-characters": 1196,
+    "hangul-characters": 1007
+  },
+  "findings": []
+}
@@ -0,0 +1,123 @@
+schema-version: 1
+verdict: NEEDS_FIX
+score: 90
+scores:
+  project-specificity:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 56
+        line-end: 83
+        content-hash: sha256:1f849db919339542195b10e26c2db6028e2acfdc0c057fcddc8cc535932c829d
+        observation: Codex 스킬 식별자, 생성 파일, 명시적 적용 명령과 적용 전 재확인을 프로젝트 고유 경로로 연결한다.
+  reader-journey:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 16
+        line-end: 85
+        content-hash: sha256:588e0fa1ad93f95c3f945ad2a8c7dcceeb414c77dd6395048955568c783a0540
+        observation: 사용자 결과, 대표 패치, Codex 요청, 생성 파일 확인, 성공 점검, 직접 적용 순서로 이어진다.
+  technical-explanation:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 105
+        line-end: 125
+        content-hash: sha256:a4bd099a77602b1510fad18ef3023498c8c6c3efb700a2d4ebdf67a1182c0f0e
+        observation: 근거 분리, 추적, 보존, 충돌·비밀·변경 차단 책임을 결과 중심으로 구분한다.
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 129
+        line-end: 137
+        content-hash: sha256:47be1e061b740eb6e3acd12179b0420cb0a3c5a6df4f599df30adbb3662dd04e
+        observation: 처리 흐름과 재작성 동작을 짧게 설명하고 상세 책임은 별도 문서로 보낸다.
+  task-usability:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 56
+        line-end: 83
+        content-hash: sha256:1f849db919339542195b10e26c2db6028e2acfdc0c057fcddc8cc535932c829d
+        observation: 요청 예시부터 결과 파일 확인과 적용까지 한 절에서 수행할 수 있다.
+  prose-clarity:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 5
+        line-end: 14
+        content-hash: sha256:c0843d3bcaf94929872e5e7ab675f77b9bbbaf66d50e8c61b6ce7d478e11c617
+        observation: 첫 문장부터 결과와 근거를 직접 밝히고 지원 범위와 미검증 범위를 분리한다.
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 195
+        line-end: 209
+        content-hash: sha256:93ace992f3430bfc7395d56e231a9c9892f959b7311d1da91f7296a8aefc29cd
+        observation: 모델 작성, 정적 확인, 도구 간 동작, 품질 비교의 한계를 짧은 항목으로 분리한다.
+  visual-judgment:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 30
+        line-end: 48
+        content-hash: sha256:ad44797cc7abc92964f888bccafdc54cc71358f07057234f9975d728d91e4927
+        observation: 대표 패치를 내부 구조보다 먼저 보여 주고 전체 패치 경로를 연결한다.
+hard-gates:
+  passed: false
+  failures: [unsupported-high-risk-claim]
+reader-simulations:
+  30-seconds:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 1
+        line-end: 14
+        content-hash: sha256:5b23dc0b21cf361bff806f69c8ed0e527528daefd523cca4ffe17ff9d3674196
+        observation: README 초안과 패치를 만드는 도구라는 점과 현재 Codex 범위를 첫 화면에서 확인한다.
+  5-minutes:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 52
+        line-end: 139
+        content-hash: sha256:002ddd5d129170e198da9c5f2b202b0b1c35e01bcefcbfe6bd3df070c04cec7e
+        observation: 최소 사용자 경로, 네 가지 모드, 안전장치와 전체 처리 흐름을 찾을 수 있다.
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 195
+        line-end: 209
+        content-hash: sha256:93ace992f3430bfc7395d56e231a9c9892f959b7311d1da91f7296a8aefc29cd
+        observation: 검증 수준, 도구 간 동일 동작과 품질 우월성의 한계를 확인할 수 있다.
+  contributor:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 158
+        line-end: 191
+        content-hash: sha256:5dd4d4f75a0efbc470683bc6c995acdf3084d7416dccd012ff6bd7fe47b0b4f7
+        observation: Python 전제조건, 개발 설치와 테스트 명령, 구현·규칙·테스트 위치를 찾을 수 있다.
+findings:
+  - id: R-001
+    severity: major
+    category: technical-correctness
+    subject: C-PROOF-001
+    section: proof
+    message: 대표 패치의 적용 완료 주장은 연결된 저장소 사실의 범위를 넘으므로 검토 통과 사실로 좁혀야 한다.
+    evidence:
+      - artifact: README.candidate.md
+        section-id: proof
+        line-start: 34
+        line-end: 35
+        content-hash: sha256:00e36e843e3370132b9c62718c3da3778bb251c1def0374182edf1723ca26df2
+        observation: C-PROOF-001은 검토와 적용 완료를 함께 말하지만 F-PROOF-001에는 PASS 출처 상태만 있다.
+    route-to: README_DRAFTED
+    status: open
@@ -0,0 +1,34 @@
+{
+  "schema-version": 1,
+  "state": "PASS_WITH_MANUAL",
+  "verification-level": "static",
+  "execution-verified": false,
+  "checks": {
+    "commands": {
+      "total": 3,
+      "verified": 1,
+      "manual-required": 2,
+      "failed": 0
+    },
+    "paths": {
+      "total": 7,
+      "verified": 7,
+      "failed": 0
+    },
+    "anchors": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    },
+    "readme-contracts": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    }
+  },
+  "failures": [],
+  "limitations": [
+    "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+    "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+  ]
+}
@@ -0,0 +1,31 @@
+schema-version: 1
+visuals:
+  - id: reviewed-patch-preview
+    section: proof
+    type: artifact-showcase
+    purpose: 검토와 적용을 마친 실제 README 패치의 핵심 변경을 보여 줍니다.
+    placeholder-text: 영문 중심 소개가 한국어 사용자 중심 소개로 바뀐 실제 diff 일부
+    must-show:
+      - 변경 전 영문 소개
+      - 변경 후 한국어 소개
+    relationships: []
+    emphasize:
+      - 입력 문서와 생성 문서의 차이
+    avoid:
+      - 저장소 근거가 없는 품질 우월성 표현
+    require-provenance: true
+    placement:
+      after-section-id: proof
+    accessibility:
+      alt-text: 영문 소개를 한국어 사용자 중심 소개로 바꾼 README 패치 미리보기
+    production:
+      format: diff
+      status: source-created
+      source-path: examples/readme-showcase/README.patch
+      source-hash: sha256:3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+    asset:
+      path: examples/readme-showcase/README.patch
+      provenance: examples/readme-showcase/provenance.yaml
+      source-run: runs/readme-harness/20260720-review-remediation
+      sha256: sha256:3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+      caption: 검토와 적용을 마친 이전 README 실행의 실제 패치 일부입니다.
@@ -0,0 +1,31 @@
+schema-version: 1
+claims:
+  - {id: C-PROJECT-001, type: factual, section: document, sources: [{fact-id: F-PROJECT-001}], status: supported}
+  - {id: C-OUTPUT-001, type: factual, section: document, sources: [{fact-id: F-VERIFY-001}, {fact-id: F-OUTPUT-001}], status: supported}
+  - {id: C-CODEX-001, type: factual, section: document, sources: [{fact-id: F-CODEX-001}], status: supported}
+  - {id: C-XTOOL-001, type: factual, section: document, sources: [{fact-id: F-CODEX-001}], status: supported}
+  - {id: C-PROOF-001, type: factual, section: proof, sources: [{fact-id: F-PROOF-001}], status: supported}
+  - {id: C-INVOCATION-001, type: factual, section: quick-start, sources: [{fact-id: F-CODEX-001}], status: supported}
+  - {id: C-RESULTS-001, type: factual, section: quick-start, sources: [{fact-id: F-OUTPUT-001}], status: supported}
+  - {id: C-NO-AUTO-APPLY-001, type: factual, section: quick-start, sources: [{fact-id: F-APPLY-001}], status: supported}
+  - {id: C-APPLY-CHECK-001, type: factual, section: quick-start, sources: [{fact-id: F-APPLY-001}], status: supported}
+  - {id: C-MODE-BOOTSTRAP-001, type: factual, section: usage, sources: [{fact-id: F-MODES-001}, {fact-id: F-OUTPUT-001}], status: supported}
+  - {id: C-MODE-AUDIT-001, type: factual, section: usage, sources: [{fact-id: F-MODES-001}, {fact-id: F-AUDIT-001}], status: supported}
+  - {id: C-MODE-REFRESH-001, type: factual, section: usage, sources: [{fact-id: F-MODES-001}, {fact-id: F-REFRESH-001}], status: supported}
+  - {id: C-MODE-SECTION-001, type: factual, section: usage, sources: [{fact-id: F-MODES-001}, {fact-id: F-SECTION-001}], status: supported}
+  - {id: C-SOURCE-SPLIT-001, type: factual, section: safeguards, sources: [{fact-id: F-AUTHORITY-001}], status: supported}
+  - {id: C-FACT-TRACE-001, type: factual, section: safeguards, sources: [{fact-id: F-CLAIM-001}, {fact-id: F-VERIFY-001}], status: supported}
+  - {id: C-PRESERVE-001, type: factual, section: safeguards, sources: [{fact-id: F-REFRESH-001}], status: supported}
+  - {id: C-CONFLICT-001, type: factual, section: safeguards, sources: [{fact-id: F-REFRESH-001}], status: supported}
+  - {id: C-SECRET-PATH-001, type: factual, section: safeguards, sources: [{fact-id: F-SAFETY-001}], status: supported}
+  - {id: C-STALE-001, type: factual, section: safeguards, sources: [{fact-id: F-SAFETY-001}, {fact-id: F-APPLY-001}], status: supported}
+  - {id: C-WORKFLOW-001, type: factual, section: workflow, sources: [{fact-id: F-WORKFLOW-001}], status: supported}
+  - {id: C-REWORK-001, type: factual, section: workflow, sources: [{fact-id: F-WORKFLOW-001}], status: supported}
+  - {id: C-REQUEST-001, type: factual, section: inputs, sources: [{fact-id: F-AUTHORITY-001}, {fact-id: F-REPO-LAYOUT-001}], status: supported}
+  - {id: C-RUN-DIR-001, type: factual, section: inputs, sources: [{fact-id: F-RUN-LAYOUT-001}], status: supported}
+  - {id: C-DEV-PREREQ-001, type: factual, section: development, sources: [{fact-id: F-RUNTIME-001}], status: supported}
+  - {id: C-LAYOUT-001, type: factual, section: documentation, sources: [{fact-id: F-REPO-LAYOUT-001}], status: supported}
+  - {id: C-WRITING-LIMIT-001, type: factual, section: limitations, sources: [{fact-id: F-VERIFY-001}], status: supported}
+  - {id: C-VERIFY-LIMIT-001, type: factual, section: limitations, sources: [{fact-id: F-VERIFY-001}], status: supported}
+  - {id: C-XTOOL-LIMIT-001, type: factual, section: limitations, sources: [{fact-id: F-CODEX-001}], status: supported}
+  - {id: C-BENCH-LIMIT-001, type: factual, section: limitations, sources: [{fact-id: F-BENCH-001}], status: supported}
@@ -0,0 +1,16 @@
+{
+  "schema-version": 1,
+  "policy-id": "korean-reader-prose-v1",
+  "language": "ko-KR",
+  "applicable": true,
+  "scope": "candidate",
+  "state": "PASS",
+  "summary": {
+    "errors": 0,
+    "warnings": 0,
+    "sentences": 52,
+    "prose-characters": 1194,
+    "hangul-characters": 1005
+  },
+  "findings": []
+}
@@ -0,0 +1,14 @@
+schema-version: 2
+mode: bootstrap
+profile: tool
+repository-snapshot-hash: sha256:2ff902bd9a7de01648f972d099614584bc26fa84c1492cec61dc6da82e4f6275
+artifacts:
+  readme-request.yaml: sha256:545161085f426a1774dec0db5d66189f817b62d5991da253115677d99746f8c2
+  repository-facts.yaml: sha256:0113f0f6acd124348d4987264ba8600492a2fe26278abb2a65309977b2ff7a69
+  readme-brief.yaml: sha256:651ac6a29ac2592ef96779b8a7387085bbdcd36575d2edd97b8bfd72a2621374
+  readme-outline.yaml: sha256:f2f5169f12e20ec51692c6341facd49689b2057fd7ea4a38b17446eb219d2f97
+  README.candidate.md: sha256:b54317f98e0bea64cc31f489caca9a541b24bbdfec3aab6af3be41d0dd4dab22
+  claim-map.yaml: sha256:194995416648414c0a18078477b0bbfd7e61ddad264efeff531bdda35ce92206
+  visual-plan.yaml: sha256:0f306a9c1ccf0c39fd636f52d4348f694bbb79e82530dbf37e08d0df063e5418
+  prose-report.json: sha256:f35a4b2bb25d3e0e1435ed3b6065313ae90e4ca4a6ef739e72c74515fb3a887f
+  review-findings.yaml: sha256:a91d19b05e2c6364dd9b424fd23d71c3829f2b244eeea9bd1a072962cfcae69e
@@ -0,0 +1,47 @@
+schema-version: 1
+project-profile:
+  primary: tool
+audiences:
+  primary:
+    - 저장소 README를 새로 만들거나 안전하게 갱신하려는 개발자
+  secondary:
+    - 하네스 검사와 프로파일을 확장하는 기여자
+reader-outcomes:
+  - 첫 두 문장에서 README 초안과 패치를 만드는 도구임을 판단한다.
+  - Codex에 작업을 요청하고 생성된 README와 패치를 확인한다.
+  - 작업에 맞는 모드를 고르고 검토한 패치만 직접 적용한다.
+  - 개발 환경과 상세 설계는 사용자 경로 뒤에서 찾는다.
+project-story:
+  value-proposition: 저장소 사실과 문서 요구를 바탕으로 README 초안을 만들고 검토용 패치로 제공합니다.
+  problem: README 작성 도구가 없는 명령을 쓰거나 사람의 문장을 덮어쓰면 검토 비용과 적용 위험이 커집니다.
+  target-reader: README를 만들거나 갱신하려는 개발자
+  notable-traits:
+    - text: 네 가지 문서 작업을 지원하며 결과를 검토용 패치로 분리합니다.
+      fact-ids: [F-MODES-001, F-OUTPUT-001]
+    - text: 명령과 경로를 확인하고 검토 전 대상 README를 바꾸지 않습니다.
+      fact-ids: [F-VERIFY-001, F-APPLY-001]
+    - text: 공개 README에는 실제 검토를 통과한 패치 예시를 연결합니다.
+      fact-ids: [F-PROOF-001]
+  maturity: Codex용 흐름은 구현됐고 Claude와 Antigravity의 같은 동작은 아직 검증하지 않았습니다.
+  limitations:
+    - README 문장은 모델이 작성하며 검사 스크립트가 문장을 대신 만들지는 않습니다.
+    - 명령 검증은 실행 기록이 없으면 정적 확인 수준입니다.
+    - 도구 간 같은 동작과 품질 우월성은 아직 주장하지 않습니다.
+narrative-variant: tool
+reader-journey:
+  - reader-question: 이 도구가 만드는 결과는 무엇입니까?
+    section-id: overview
+  - reader-question: 실제 결과는 어떤 모습입니까?
+    section-id: proof
+  - reader-question: 가장 짧은 사용자 경로는 무엇입니까?
+    section-id: quick-start
+  - reader-question: 작업에 맞는 모드는 무엇입니까?
+    section-id: usage
+  - reader-question: 적용 전에 무엇을 확인합니까?
+    section-id: safeguards
+  - reader-question: 하네스는 어떤 순서로 일합니까?
+    section-id: workflow
+  - reader-question: 사용자에게 필요한 파일은 무엇입니까?
+    section-id: inputs
+  - reader-question: 개발과 상세 설계는 어디서 확인합니까?
+    section-id: development
@@ -0,0 +1,78 @@
+schema-version: 1
+sections:
+  - id: overview
+    title-guidance: 무엇을 만드는가
+    level: 2
+    purpose: 프로젝트 결과와 현재 지원 범위를 첫 화면에서 설명합니다.
+    required: true
+    content-strategy: inline
+    content-requirements:
+      - README 초안과 패치
+      - Codex 지원과 다른 도구의 미검증 범위
+  - id: proof
+    title-guidance: 실제 결과
+    level: 2
+    purpose: 검토를 통과한 실제 패치 일부를 먼저 보여 줍니다.
+    required: true
+    content-strategy: inline
+    content-requirements:
+      - 실제 이전 실행의 패치 미리보기
+      - 전체 패치와 출처 링크
+    visual-slot:
+      decision: include
+      reader-question: 이 도구가 만든 실제 README 변경은 어떤 모습입니까?
+      rationale: 결과가 문서인 도구는 내부 구조도보다 실제 변경 내용을 먼저 보여 줘야 합니다.
+      purpose: 이전 실행에서 검토와 적용을 마친 README 패치 일부를 보여 줍니다.
+  - id: quick-start
+    title-guidance: 빠른 시작
+    level: 2
+    purpose: Codex 요청부터 결과 확인과 명시적 적용까지의 기본 경로를 제공합니다.
+    required: true
+    content-strategy: inline
+    content-requirements:
+      - 사용자 요청
+      - 생성 파일
+      - 성공 확인
+      - 명시적 적용
+  - id: usage
+    title-guidance: 어떤 작업을 지원하는가
+    level: 2
+    purpose: 기본 모드와 세 보조 모드를 독자 작업 기준으로 구분합니다.
+    required: true
+    content-strategy: inline
+  - id: safeguards
+    title-guidance: 안전하게 다루는 방법
+    level: 2
+    purpose: 근거 확인과 사람 작성 내용 보존, 자동 적용 금지를 설명합니다.
+    required: true
+    content-strategy: inline
+  - id: workflow
+    title-guidance: 동작 방식
+    level: 2
+    purpose: 사용자 관점의 처리 순서만 짧게 보여 줍니다.
+    required: true
+    content-strategy: inline
+  - id: inputs
+    title-guidance: 입력과 생성 파일
+    level: 2
+    purpose: 사용자가 준비하고 확인할 파일만 설명합니다.
+    required: true
+    content-strategy: inline
+  - id: development
+    title-guidance: 개발
+    level: 2
+    purpose: 기여자용 설치와 테스트 경로를 사용자 경로 뒤에 둡니다.
+    required: true
+    content-strategy: inline
+  - id: documentation
+    title-guidance: 상세 문서
+    level: 2
+    purpose: 내부 구조와 정책을 정본 문서로 연결합니다.
+    required: true
+    content-strategy: inline
+  - id: limitations
+    title-guidance: 현재 한계
+    level: 2
+    purpose: 모델 작성과 검증 수준, 도구 지원 범위를 한곳에 정리합니다.
+    required: true
+    content-strategy: inline
@@ -0,0 +1,78 @@
+schema-version: 1
+target:
+  repository: /home/donghyeon/workspace/ai-tool/readme-harness
+  readme-path: README.md
+mode: bootstrap
+profile-override: tool
+project-intent:
+  purpose: 저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안과 검토용 패치를 만드는 도구를 설명한다.
+  positioning: 사용자 경로를 먼저 보여 주고, 명령·경로·문장 근거 검사와 사람 작성 내용 보존은 필요한 수준에서만 설명한다.
+  maturity: 현재 Codex용 작성·검증 흐름을 지원하며 Claude와 Antigravity의 동일 동작은 아직 검증하지 않았다.
+audience:
+  primary:
+    - 저장소 README를 새로 만들거나 안전하게 갱신하려는 개발자
+  secondary:
+    - 하네스 검사와 프로파일을 확장하는 기여자
+reader-actions:
+  - 첫 두 문장에서 어떤 결과를 만드는 도구인지 판단한다.
+  - Codex에 README 작업을 요청하고 생성된 README와 패치를 확인한다.
+  - 작업 목적에 맞는 모드를 고른다.
+  - 검토한 패치만 명시적으로 적용한다.
+  - 개발 환경과 테스트 방법은 별도의 개발 절에서 찾는다.
+content-policy:
+  language: ko-KR
+  tone: 독자 행동을 먼저 밝히는 직접적인 기술 설명체
+  target-length: medium
+  preserve-existing-copy: false
+  detail-docs-policy: summary-and-link
+visual-policy:
+  mode: when-useful
+  max-visuals: 1
+  preferred-formats:
+    - diff
+  placeholder-format: HTML 주석 기반 제작 사양
+terminology-policy:
+  exact-identifiers: []
+  explain-on-first-use: {}
+  internal-only:
+    family: 작업 담당 방식
+    fan-out: 여러 담당자가 나눠 검토
+    collapse: 한 담당자가 맡아 처리
+    concrete worker: 실제 변경 담당자
+    verification family: 검증 담당 역할
+    route-to: 다시 작성할 지점
+public-surface-terms:
+  allowed:
+    - bootstrap
+    - audit
+    - refresh
+    - section-update
+    - readme-request.yaml
+    - README.generated.md
+    - README.patch
+    - requirement-driven-readme
+  explain-on-first-use: {}
+  docs-only:
+    - QUALITY_REVIEWED
+    - READY_FOR_APPLY
+    - claim-map.yaml
+    - visual-plan.yaml
+    - review-findings.yaml
+    - quality-manifest.yaml
+must-include:
+  - 한 문장 설명과 Codex 지원 범위
+  - 실제 검토를 통과한 패치 미리보기와 원본 파일 링크
+  - Codex 스킬 요청부터 생성 파일 확인, 성공 확인, 명시적 적용까지의 기본 사용자 경로
+  - bootstrap을 기본 경로로 두고 audit, refresh, section-update를 보조 경로로 설명
+  - 코드에서 확인한 사실, 사람 작성 내용 보존, 자동 적용 금지, 변경·비밀 값 차단 요약
+  - 사용자 입력과 생성 파일을 세 개에서 네 개 수준으로 요약
+  - 개발 환경 설치와 전체 테스트를 사용자 경로 뒤의 개발 절에 배치
+  - 아키텍처, 시각 자료, 상태, 사용량, 품질 비교 상세 문서 링크
+  - 현재 Codex 지원과 다른 도구의 동일 동작 미검증 한계
+must-exclude:
+  - 빠른 시작의 첫 행동으로 테스트나 개발 의존성 설치를 제시하는 구성
+  - 공개 README에서 내부 상태 이름, 내부 결과 파일, 게이트 계약을 설명하는 문장
+  - 저장소 근거 없는 성능·품질 우월성 주장
+  - 한 주장 마커가 여러 사실 문장을 덮는 구성
+  - 제품 결과보다 먼저 나오는 내부 구조도
+protected-sections: []
@@ -0,0 +1,387 @@
+schema-version: 1
+repository-snapshot-hash: sha256:2ff902bd9a7de01648f972d099614584bc26fa84c1492cec61dc6da82e4f6275
+project-name: readme-harness
+languages: [Python, Markdown, YAML]
+frameworks: []
+facts:
+  - id: F-PROJECT-001
+    category: project
+    key: identity
+    value:
+      name: readme-harness
+      version: 0.1.0
+      purpose: 저장소 사실과 사용자 요구를 바탕으로 GitHub README를 분석·설계·작성·검증합니다.
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 2
+        line-end: 6
+      - path: pyproject.toml
+        source-kind: build-manifest
+        line-start: 1
+        line-end: 4
+  - id: F-RUNTIME-001
+    category: prerequisites
+    key: python-and-development
+    value:
+      python-minimum: "3.12"
+      runtime-packages: [jsonschema, PyYAML]
+      development-tool: pytest
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: pyproject.toml
+        source-kind: build-manifest
+        line-start: 1
+        line-end: 13
+  - id: F-TOOL-PROFILE-001
+    category: audience
+    key: tool-profile
+    value:
+      primary-outcome: reviewed-patch-created
+      max-primary-steps: 4
+      development-command-as-first-step: false
+      representative-proof-required: true
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: .agents/profiles/tool.yaml
+        source-kind: profile
+        line-start: 1
+        line-end: 21
+  - id: F-MODES-001
+    category: capability
+    key: implemented-modes
+    value: [bootstrap, audit, refresh, section-update]
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 10
+        line-end: 13
+  - id: F-WORKFLOW-001
+    category: workflow
+    key: public-flow
+    value: 사용자 요구와 저장소 근거를 분리해 계획하고, 모델 작성 뒤 검사와 독립 검토를 거쳐 패치 준비와 명시적 적용으로 이어집니다.
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: docs/architecture.md
+        source-kind: documentation
+        line-start: 3
+        line-end: 49
+      - path: .agents/skills/requirement-driven-readme/SKILL.md
+        source-kind: skill-contract
+        line-start: 27
+        line-end: 45
+  - id: F-AUDIT-001
+    category: workflow
+    key: audit-behavior
+    value: audit는 기존 README를 점검하며 대체 README나 패치를 만들지 않습니다.
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: docs/state-machine.md
+        source-kind: documentation
+        line-start: 19
+        line-end: 23
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 53
+        line-end: 55
+  - id: F-REFRESH-001
+    category: safeguard
+    key: refresh-merge-policy
+    value:
+      protected: never-modify
+      unmarked: preserve
+      managed: regenerate-or-3way-merge
+      conflict-result: block
+      post-merge-validation: required
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 82
+        line-end: 100
+      - path: docs/state-machine.md
+        source-kind: documentation
+        line-start: 25
+        line-end: 29
+  - id: F-SECTION-001
+    category: workflow
+    key: section-update-behavior
+    value: section-update는 선택한 섹션의 의존 결과를 무효화한 뒤 전체 문서 검증과 명시적 적용 경계를 다시 거칩니다.
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: docs/state-machine.md
+        source-kind: documentation
+        line-start: 31
+        line-end: 36
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 116
+        line-end: 122
+  - id: F-VERIFY-001
+    category: architecture
+    key: editorial-and-verification-separation
+    value: 모델 역할이 문장을 작성하고 Python 검사가 근거, 문장, 명령, 경로, 링크, 비밀 값, 그림, 해시와 적용 경계를 확인합니다.
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: docs/architecture.md
+        source-kind: documentation
+        line-start: 3
+        line-end: 6
+      - path: docs/architecture.md
+        source-kind: documentation
+        line-start: 40
+        line-end: 49
+  - id: F-AUTHORITY-001
+    category: trust
+    key: evidence-authority
+    value:
+      technical-facts-source: repository-facts.yaml
+      intent-source: readme-request.yaml
+      repository-content-trust: untrusted-data
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/SKILL.md
+        source-kind: skill-contract
+        line-start: 27
+        line-end: 29
+      - path: docs/architecture.md
+        source-kind: documentation
+        line-start: 67
+        line-end: 72
+  - id: F-CLAIM-001
+    category: safeguard
+    key: factual-claim-traceability
+    value: 사실 주장은 알려진 근거 ID를 참조해야 하며 한 claim-id 마커는 정확히 한 문장만 가리킵니다.
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/claims.py
+        source-kind: implementation
+        symbol: validate_claim_map
+        line-start: 45
+        line-end: 100
+  - id: F-PROSE-001
+    category: safeguard
+    key: reader-prose-validation
+    value: 같은 문단의 연속 줄을 합친 뒤 문장 길이와 표현을 검사하며 목록과 표의 각 항목은 따로 검사합니다.
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/prose.py
+        source-kind: implementation
+        symbol: _visible_lines
+        line-start: 82
+        line-end: 150
+      - path: tests/unit/test_prose.py
+        source-kind: test
+        symbol: test_hard_wrapped_paragraph_is_joined_before_sentence_length_check
+        line-start: 110
+        line-end: 126
+  - id: F-VISUAL-001
+    category: visual
+    key: representative-output-policy
+    value: 실제 결과 증명은 저장소의 지속 경로와 검토된 출처, 파일 해시를 가져야 합니다.
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: docs/visuals.md
+        source-kind: documentation
+        line-start: 3
+        line-end: 27
+      - path: .agents/profiles/tool.yaml
+        source-kind: profile
+        line-start: 15
+        line-end: 21
+  - id: F-OUTPUT-001
+    category: safeguard
+    key: patch-preparation
+    value:
+      target: README.md
+      outputs: [README.generated.md, README.patch, apply-manifest.yaml]
+      checks: [repository-freshness, reviewed-artifact-hashes, target-path-containment]
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/scripts/generate_patch.py
+        source-kind: implementation
+        symbol: main
+        line-start: 25
+        line-end: 89
+  - id: F-APPLY-001
+    category: safeguard
+    key: explicit-apply
+    value:
+      command-identifier: apply_patch.py
+      target: README.md
+      checks: [generated-hash, repository-freshness, path-containment, target-before-hash]
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
+        source-kind: implementation
+        symbol: main
+        line-start: 22
+        line-end: 67
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 141
+        line-end: 148
+  - id: F-BENCH-001
+    category: limitation
+    key: quality-superiority
+    value:
+      current-status: not-run
+      claim-policy: prohibited-until-benchmark-pass
+      benchmark: benchmarks/quality-benchmark.yaml
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 109
+        line-end: 114
+      - path: docs/quality-benchmark.md
+        source-kind: documentation
+        line-start: 3
+        line-end: 36
+  - id: F-PROOF-001
+    category: representative-output
+    key: reviewed-patch-showcase
+    value:
+      path: examples/readme-showcase/README.patch
+      media-type: text/x-diff
+      source-status: PASS
+      sha256: 3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: examples/readme-showcase/provenance.yaml
+        source-kind: provenance-record
+        line-start: 1
+        line-end: 9
+  - id: F-CODEX-001
+    category: capability
+    key: codex-skill-and-cross-tool-support
+    value:
+      skill-identifier: requirement-driven-readme
+      codex-path-drivers: implemented
+      supported-tools: [codex, antigravity, claude]
+      claude-antigravity-runtime-equivalence: phase-4-conformance-goal
+    assertion-type: derived
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/SKILL.md
+        source-kind: skill-contract
+        line-start: 2
+        line-end: 9
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 8
+        line-end: 13
+      - path: docs/architecture.md
+        source-kind: documentation
+        line-start: 32
+        line-end: 34
+  - id: F-RUN-LAYOUT-001
+    category: layout
+    key: run-directory
+    value:
+      canonical: "runs/<repo-id>/<run-id>/"
+      public-form: "runs/<repo-id>/<run-id>"
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 137
+        line-end: 139
+      - path: .agents/skills/requirement-driven-readme/SKILL.md
+        source-kind: skill-contract
+        line-start: 38
+        line-end: 39
+  - id: F-REPO-LAYOUT-001
+    category: layout
+    key: repository-paths
+    value:
+      implementation: src/readme_harness
+      rules-and-workflows: .agents
+      tests: tests
+      request-file: readme-request.yaml
+    assertion-type: derived
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        source-kind: project-manifest
+        line-start: 132
+        line-end: 139
+      - path: pyproject.toml
+        source-kind: build-manifest
+        line-start: 14
+        line-end: 19
+      - path: docs/architecture.md
+        source-kind: documentation
+        line-start: 7
+        line-end: 49
+  - id: F-SAFETY-001
+    category: safeguard
+    key: stale-secret-and-path-protection
+    value:
+      stale-snapshot: blocks-patch-generation-and-apply
+      secret-values: forbidden-in-facts-and-readme
+      target-path: must-resolve-inside-repository
+      out-of-tree-symlinks: findings-not-traversal-targets
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/scripts/generate_patch.py
+        source-kind: implementation
+        line-start: 46
+        line-end: 68
+      - path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
+        source-kind: implementation
+        line-start: 46
+        line-end: 61
+      - path: .agents/rules/repository-content-trust.md
+        source-kind: policy
+        line-start: 13
+        line-end: 28
+commands:
+  - id: CMD-001
+    command: python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+    cwd: .
+    source:
+      path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
+      source-kind: implementation
+    verification:
+      status: discovered
+      method: python-script-existence
+  - id: CMD-002
+    command: python3 -m pip install -e ".[dev]"
+    cwd: .
+    source:
+      path: pyproject.toml
+      source-kind: build-manifest
+    verification:
+      status: declared
+      method: pyproject-optional-dependencies
+  - id: CMD-003
+    command: python3 -m pytest -q
+    cwd: .
+    source:
+      path: pyproject.toml
+      source-kind: build-manifest
+    verification:
+      status: declared
+      method: pytest-configuration
@@ -0,0 +1,7 @@
+{
+  "git-sha": "636617ccd9f20440f21339f808557c096b55fec2",
+  "dirty": true,
+  "diff-hash": "sha256:2ff902bd9a7de01648f972d099614584bc26fa84c1492cec61dc6da82e4f6275",
+  "scanned-at": null,
+  "file-count": 231
+}
@@ -0,0 +1,55 @@
+schema-version: 1
+verdict: PASS
+score: 90
+scores:
+  project-specificity:
+    score: 5
+    evidence:
+      - {artifact: README.candidate.md, section-id: quick-start, line-start: 56, line-end: 83, content-hash: "sha256:1f849db919339542195b10e26c2db6028e2acfdc0c057fcddc8cc535932c829d", observation: "Codex 스킬부터 생성 파일과 명시적 적용까지 프로젝트 고유 경로를 보여 준다."}
+  reader-journey:
+    score: 5
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 16, line-end: 85, content-hash: "sha256:b321d79f0e9891648e916dd64a486bf562e54950ad960d1d898f4a4ccf3efa72", observation: "사용자 결과와 대표 패치, 요청, 확인, 적용 순서로 이어진다."}
+  technical-explanation:
+    score: 4
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 105, line-end: 125, content-hash: "sha256:a4bd099a77602b1510fad18ef3023498c8c6c3efb700a2d4ebdf67a1182c0f0e", observation: "근거 분리와 보존, 충돌·비밀·변경 차단 책임을 결과 중심으로 구분한다."}
+  task-usability:
+    score: 4
+    evidence:
+      - {artifact: README.candidate.md, section-id: quick-start, line-start: 56, line-end: 83, content-hash: "sha256:1f849db919339542195b10e26c2db6028e2acfdc0c057fcddc8cc535932c829d", observation: "요청 예시부터 결과 파일 확인과 적용까지 한 절에서 수행할 수 있다."}
+  prose-clarity:
+    score: 4
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 5, line-end: 14, content-hash: "sha256:c0843d3bcaf94929872e5e7ab675f77b9bbbaf66d50e8c61b6ce7d478e11c617", observation: "첫 문장부터 결과와 범위를 직접 밝히며 한국어 문체 검사 경고가 없다."}
+  visual-judgment:
+    score: 5
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 30, line-end: 48, content-hash: "sha256:aa73ed11c4b75d71efa7899fbdff8803d6cbd59ba9c9c20597b1d8c6fa9dca90", observation: "검토 통과 상태의 대표 패치를 내부 구조보다 먼저 보여 준다."}
+hard-gates:
+  passed: true
+  failures: []
+reader-simulations:
+  30-seconds:
+    outcome: PASS
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 1, line-end: 14, content-hash: "sha256:5b23dc0b21cf361bff806f69c8ed0e527528daefd523cca4ffe17ff9d3674196", observation: "README 초안과 패치를 만드는 도구와 현재 Codex 범위를 첫 화면에서 확인한다."}
+  5-minutes:
+    outcome: PASS
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 52, line-end: 139, content-hash: "sha256:002ddd5d129170e198da9c5f2b202b0b1c35e01bcefcbfe6bd3df070c04cec7e", observation: "최소 사용자 경로, 네 모드, 안전장치와 전체 처리 흐름을 찾을 수 있다."}
+  contributor:
+    outcome: PASS
+    evidence:
+      - {artifact: README.candidate.md, section-id: document, line-start: 158, line-end: 191, content-hash: "sha256:5dd4d4f75a0efbc470683bc6c995acdf3084d7416dccd012ff6bd7fe47b0b4f7", observation: "개발 설치와 테스트 명령, 구현·규칙·테스트 위치를 찾을 수 있다."}
+findings:
+  - id: R-001
+    severity: major
+    category: technical-correctness
+    subject: C-PROOF-001
+    section: proof
+    message: 적용 완료 과잉 주장을 제거하고 검토 통과 사실만 남겼다.
+    evidence:
+      - {artifact: README.candidate.md, section-id: proof, line-start: 34, line-end: 35, content-hash: "sha256:dedc8a48d038f220392c136a4e6cf0544c53d12f6f2572744cf4f936892f4517", observation: "현재 문장은 F-PROOF-001이 기록한 검토 통과 상태만 주장한다."}
+    route-to: README_DRAFTED
+    status: resolved
@@ -0,0 +1,22 @@
+# README quality review
+
+Verdict: **PASS** — 90/100
+
+## Dimension scores
+
+- project-specificity: 5/5
+- reader-journey: 5/5
+- technical-explanation: 4/5
+- task-usability: 4/5
+- prose-clarity: 4/5
+- visual-judgment: 5/5
+
+## Reader simulations
+
+- 30-seconds: PASS
+- 5-minutes: PASS
+- contributor: PASS
+
+## Findings
+
+- [major] R-001 (proof): 적용 완료 과잉 주장을 제거하고 검토 통과 사실만 남겼다.
@@ -0,0 +1,12 @@
+{
+  "schema-version": 1,
+  "run-id": "20260720-public-readme-r2",
+  "repo-id": "readme-harness",
+  "mode": "bootstrap",
+  "target-repository": "/home/donghyeon/workspace/ai-tool/readme-harness",
+  "harness-version": "0.1.0",
+  "started-at": null,
+  "tool-adapter": "codex",
+  "input-hashes": {},
+  "usage": {}
+}
@@ -0,0 +1,567 @@
+{
+  "schema-version": 1,
+  "mode": "bootstrap",
+  "current": "READY_FOR_APPLY",
+  "history": [
+    {
+      "state": "INITIALIZED"
+    },
+    {
+      "state": "INPUT_CAPTURED",
+      "gates": [
+        {
+          "name": "request",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        }
+      ]
+    },
+    {
+      "state": "REPOSITORY_SNAPSHOTTED",
+      "gates": [
+        {
+          "name": "snapshot",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "diff-hash": "sha256:77b1a19a536615064a4894d23c78b2e7aa54a9ef4cf13bad194ae40565407951"
+          }
+        }
+      ]
+    },
+    {
+      "state": "FACTS_EXTRACTED",
+      "gates": [
+        {
+          "name": "facts",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "fact_ids": [
+              "F-PROJECT-001",
+              "F-RUNTIME-001",
+              "F-TOOL-PROFILE-001",
+              "F-MODES-001",
+              "F-WORKFLOW-001",
+              "F-AUDIT-001",
+              "F-REFRESH-001",
+              "F-SECTION-001",
+              "F-VERIFY-001",
+              "F-AUTHORITY-001",
+              "F-CLAIM-001",
+              "F-PROSE-001",
+              "F-VISUAL-001",
+              "F-OUTPUT-001",
+              "F-APPLY-001",
+              "F-BENCH-001",
+              "F-PROOF-001",
+              "F-CODEX-001",
+              "F-RUN-LAYOUT-001",
+              "F-REPO-LAYOUT-001",
+              "F-SAFETY-001"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "PROJECT_PROFILED",
+      "gates": [
+        {
+          "name": "profile",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "profile": "tool"
+          }
+        }
+      ]
+    },
+    {
+      "state": "README_PLANNED",
+      "gates": [
+        {
+          "name": "brief",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        },
+        {
+          "name": "outline",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "section_ids": [
+              "overview",
+              "proof",
+              "quick-start",
+              "usage",
+              "safeguards",
+              "workflow",
+              "inputs",
+              "development",
+              "documentation",
+              "limitations"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "README_DRAFTED",
+      "gates": [
+        {
+          "name": "conformance",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "sections": [
+              "overview",
+              "proof",
+              "quick-start",
+              "usage",
+              "safeguards",
+              "workflow",
+              "inputs",
+              "development",
+              "documentation",
+              "limitations"
+            ]
+          }
+        },
+        {
+          "name": "claim_map",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "claims": [
+              "C-PROJECT-001",
+              "C-OUTPUT-001",
+              "C-CODEX-001",
+              "C-XTOOL-001",
+              "C-PROOF-001",
+              "C-INVOCATION-001",
+              "C-RESULTS-001",
+              "C-NO-AUTO-APPLY-001",
+              "C-APPLY-CHECK-001",
+              "C-MODE-BOOTSTRAP-001",
+              "C-MODE-AUDIT-001",
+              "C-MODE-REFRESH-001",
+              "C-MODE-SECTION-001",
+              "C-SOURCE-SPLIT-001",
+              "C-FACT-TRACE-001",
+              "C-PRESERVE-001",
+              "C-CONFLICT-001",
+              "C-SECRET-PATH-001",
+              "C-STALE-001",
+              "C-WORKFLOW-001",
+              "C-REWORK-001",
+              "C-REQUEST-001",
+              "C-RUN-DIR-001",
+              "C-DEV-PREREQ-001",
+              "C-LAYOUT-001",
+              "C-WRITING-LIMIT-001",
+              "C-VERIFY-LIMIT-001",
+              "C-XTOOL-LIMIT-001",
+              "C-BENCH-LIMIT-001"
+            ],
+            "derived-statements": {
+              "C-PROJECT-001": "저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.",
+              "C-OUTPUT-001": "명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.",
+              "C-CODEX-001": "현재 지원하는 작성·검증 흐름은 Codex용입니다.",
+              "C-XTOOL-001": "Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.",
+              "C-PROOF-001": "아래 내용은 검토와 적용을 마친 이전 실행의 패치 일부입니다.",
+              "C-INVOCATION-001": "현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.",
+              "C-RESULTS-001": "<!-- quick-start-step: expected-result -->\n작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.",
+              "C-NO-AUTO-APPLY-001": "대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.",
+              "C-APPLY-CHECK-001": "적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.",
+              "C-MODE-BOOTSTRAP-001": "새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.",
+              "C-MODE-AUDIT-001": "현재 README의 문제만 찾는 작업은 `audit`입니다.",
+              "C-MODE-REFRESH-001": "사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.",
+              "C-MODE-SECTION-001": "한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.",
+              "C-SOURCE-SPLIT-001": "코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.",
+              "C-FACT-TRACE-001": "명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.",
+              "C-PRESERVE-001": "갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.",
+              "C-CONFLICT-001": "사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.",
+              "C-SECRET-PATH-001": "비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.",
+              "C-STALE-001": "검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.",
+              "C-WORKFLOW-001": "사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용",
+              "C-REWORK-001": "검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.",
+              "C-REQUEST-001": "`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.",
+              "C-RUN-DIR-001": "각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.",
+              "C-DEV-PREREQ-001": "개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.",
+              "C-LAYOUT-001": "주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.",
+              "C-WRITING-LIMIT-001": "- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.",
+              "C-VERIFY-LIMIT-001": "- 실행 기록이 없는 명령은 정적으로만 확인합니다.",
+              "C-XTOOL-LIMIT-001": "- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.",
+              "C-BENCH-LIMIT-001": "- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다."
+            }
+          }
+        }
+      ]
+    },
+    {
+      "state": "VISUALS_PLANNED",
+      "gates": [
+        {
+          "name": "visual_plan",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "visuals": [
+              "reviewed-patch-preview"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "STRUCTURALLY_VALIDATED",
+      "gates": [
+        {
+          "name": "github_markdown",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        },
+        {
+          "name": "reader_prose",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "schema-version": 1,
+            "policy-id": "korean-reader-prose-v1",
+            "language": "ko-KR",
+            "applicable": true,
+            "scope": "candidate",
+            "state": "PASS",
+            "summary": {
+              "errors": 0,
+              "warnings": 0,
+              "sentences": 52,
+              "prose-characters": 1196,
+              "hangul-characters": 1007
+            },
+            "findings": []
+          }
+        }
+      ]
+    },
+    {
+      "state": "TECHNICALLY_VERIFIED",
+      "gates": [
+        {
+          "name": "verify",
+          "ok": true,
+          "warnings": [
+            "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+            "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+          ],
+          "data": {
+            "schema-version": 1,
+            "state": "PASS_WITH_MANUAL",
+            "verification-level": "static",
+            "execution-verified": false,
+            "checks": {
+              "commands": {
+                "total": 3,
+                "verified": 1,
+                "manual-required": 2,
+                "failed": 0
+              },
+              "paths": {
+                "total": 7,
+                "verified": 7,
+                "failed": 0
+              },
+              "anchors": {
+                "total": 0,
+                "verified": 0,
+                "failed": 0
+              },
+              "readme-contracts": {
+                "total": 0,
+                "verified": 0,
+                "failed": 0
+              }
+            },
+            "failures": [],
+            "limitations": [
+              "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+              "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+            ]
+          }
+        },
+        {
+          "name": "secret_scan",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        }
+      ]
+    },
+    {
+      "state": "README_PLANNED",
+      "from": "TECHNICALLY_VERIFIED",
+      "resumed": true,
+      "resume-from": "README_DRAFTED",
+      "invalidated": [
+        "README.candidate.md",
+        "claim-map.yaml",
+        "visual-plan.yaml",
+        "prose-report.json",
+        "verification.json",
+        "review-findings.yaml"
+      ]
+    },
+    {
+      "state": "README_DRAFTED",
+      "gates": [
+        {
+          "name": "conformance",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "sections": [
+              "overview",
+              "proof",
+              "quick-start",
+              "usage",
+              "safeguards",
+              "workflow",
+              "inputs",
+              "development",
+              "documentation",
+              "limitations"
+            ]
+          }
+        },
+        {
+          "name": "claim_map",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "claims": [
+              "C-PROJECT-001",
+              "C-OUTPUT-001",
+              "C-CODEX-001",
+              "C-XTOOL-001",
+              "C-PROOF-001",
+              "C-INVOCATION-001",
+              "C-RESULTS-001",
+              "C-NO-AUTO-APPLY-001",
+              "C-APPLY-CHECK-001",
+              "C-MODE-BOOTSTRAP-001",
+              "C-MODE-AUDIT-001",
+              "C-MODE-REFRESH-001",
+              "C-MODE-SECTION-001",
+              "C-SOURCE-SPLIT-001",
+              "C-FACT-TRACE-001",
+              "C-PRESERVE-001",
+              "C-CONFLICT-001",
+              "C-SECRET-PATH-001",
+              "C-STALE-001",
+              "C-WORKFLOW-001",
+              "C-REWORK-001",
+              "C-REQUEST-001",
+              "C-RUN-DIR-001",
+              "C-DEV-PREREQ-001",
+              "C-LAYOUT-001",
+              "C-WRITING-LIMIT-001",
+              "C-VERIFY-LIMIT-001",
+              "C-XTOOL-LIMIT-001",
+              "C-BENCH-LIMIT-001"
+            ],
+            "derived-statements": {
+              "C-PROJECT-001": "저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.",
+              "C-OUTPUT-001": "명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.",
+              "C-CODEX-001": "현재 지원하는 작성·검증 흐름은 Codex용입니다.",
+              "C-XTOOL-001": "Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.",
+              "C-PROOF-001": "아래 내용은 검토를 통과한 이전 실행의 패치 일부입니다.",
+              "C-INVOCATION-001": "현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.",
+              "C-RESULTS-001": "<!-- quick-start-step: expected-result -->\n작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.",
+              "C-NO-AUTO-APPLY-001": "대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.",
+              "C-APPLY-CHECK-001": "적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.",
+              "C-MODE-BOOTSTRAP-001": "새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.",
+              "C-MODE-AUDIT-001": "현재 README의 문제만 찾는 작업은 `audit`입니다.",
+              "C-MODE-REFRESH-001": "사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.",
+              "C-MODE-SECTION-001": "한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.",
+              "C-SOURCE-SPLIT-001": "코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.",
+              "C-FACT-TRACE-001": "명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.",
+              "C-PRESERVE-001": "갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.",
+              "C-CONFLICT-001": "사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.",
+              "C-SECRET-PATH-001": "비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.",
+              "C-STALE-001": "검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.",
+              "C-WORKFLOW-001": "사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용",
+              "C-REWORK-001": "검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.",
+              "C-REQUEST-001": "`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.",
+              "C-RUN-DIR-001": "각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.",
+              "C-DEV-PREREQ-001": "개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.",
+              "C-LAYOUT-001": "주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.",
+              "C-WRITING-LIMIT-001": "- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.",
+              "C-VERIFY-LIMIT-001": "- 실행 기록이 없는 명령은 정적으로만 확인합니다.",
+              "C-XTOOL-LIMIT-001": "- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.",
+              "C-BENCH-LIMIT-001": "- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다."
+            }
+          }
+        }
+      ]
+    },
+    {
+      "state": "VISUALS_PLANNED",
+      "gates": [
+        {
+          "name": "visual_plan",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "visuals": [
+              "reviewed-patch-preview"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "STRUCTURALLY_VALIDATED",
+      "gates": [
+        {
+          "name": "github_markdown",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        },
+        {
+          "name": "reader_prose",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "schema-version": 1,
+            "policy-id": "korean-reader-prose-v1",
+            "language": "ko-KR",
+            "applicable": true,
+            "scope": "candidate",
+            "state": "PASS",
+            "summary": {
+              "errors": 0,
+              "warnings": 0,
+              "sentences": 52,
+              "prose-characters": 1194,
+              "hangul-characters": 1005
+            },
+            "findings": []
+          }
+        }
+      ]
+    },
+    {
+      "state": "TECHNICALLY_VERIFIED",
+      "gates": [
+        {
+          "name": "verify",
+          "ok": true,
+          "warnings": [
+            "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+            "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+          ],
+          "data": {
+            "schema-version": 1,
+            "state": "PASS_WITH_MANUAL",
+            "verification-level": "static",
+            "execution-verified": false,
+            "checks": {
+              "commands": {
+                "total": 3,
+                "verified": 1,
+                "manual-required": 2,
+                "failed": 0
+              },
+              "paths": {
+                "total": 7,
+                "verified": 7,
+                "failed": 0
+              },
+              "anchors": {
+                "total": 0,
+                "verified": 0,
+                "failed": 0
+              },
+              "readme-contracts": {
+                "total": 0,
+                "verified": 0,
+                "failed": 0
+              }
+            },
+            "failures": [],
+            "limitations": [
+              "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+              "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+            ]
+          }
+        },
+        {
+          "name": "secret_scan",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        }
+      ]
+    },
+    {
+      "state": "QUALITY_REVIEWED",
+      "gates": [
+        {
+          "name": "review",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "verdict": "PASS",
+            "score": 90,
+            "findings": [
+              {
+                "id": "R-001",
+                "severity": "major",
+                "category": "technical-correctness",
+                "subject": "C-PROOF-001",
+                "section": "proof",
+                "message": "적용 완료 과잉 주장을 제거하고 검토 통과 사실만 남겼다.",
+                "evidence": [
+                  {
+                    "artifact": "README.candidate.md",
+                    "section-id": "proof",
+                    "line-start": 34,
+                    "line-end": 35,
+                    "content-hash": "sha256:dedc8a48d038f220392c136a4e6cf0544c53d12f6f2572744cf4f936892f4517",
+                    "observation": "현재 문장은 F-PROOF-001이 기록한 검토 통과 상태만 주장한다."
+                  }
+                ],
+                "route-to": "README_DRAFTED",
+                "status": "resolved"
+              }
+            ],
+            "report-valid": true
+          }
+        }
+      ]
+    },
+    {
+      "state": "READY_FOR_APPLY",
+      "gates": []
+    }
+  ],
+  "rework": {
+    "iterations": 1,
+    "findings": {
+      "sha256:9c9a7da5c0916b83": {
+        "attempts": 1,
+        "status": "open",
+        "latest-id": "R-001"
+      }
+    }
+  },
+  "reasons": [
+    "R-001"
+  ],
+  "resume-from": "README_DRAFTED"
+}
@@ -0,0 +1,34 @@
+{
+  "schema-version": 1,
+  "state": "PASS_WITH_MANUAL",
+  "verification-level": "static",
+  "execution-verified": false,
+  "checks": {
+    "commands": {
+      "total": 3,
+      "verified": 1,
+      "manual-required": 2,
+      "failed": 0
+    },
+    "paths": {
+      "total": 7,
+      "verified": 7,
+      "failed": 0
+    },
+    "anchors": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    },
+    "readme-contracts": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    }
+  },
+  "failures": [],
+  "limitations": [
+    "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+    "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+  ]
+}
@@ -0,0 +1,26 @@
+schema-version: 1
+visuals:
+  - id: reviewed-patch-preview
+    section: proof
+    type: artifact-showcase
+    purpose: 검토를 통과한 실제 README 패치의 핵심 변경을 보여 줍니다.
+    placeholder-text: 영문 중심 소개가 한국어 사용자 중심 소개로 바뀐 실제 diff 일부
+    must-show: [변경 전 영문 소개, 변경 후 한국어 소개]
+    relationships: []
+    emphasize: [입력 문서와 생성 문서의 차이]
+    avoid: [저장소 근거가 없는 품질 우월성 표현]
+    require-provenance: true
+    placement: {after-section-id: proof}
+    accessibility:
+      alt-text: 영문 소개를 한국어 사용자 중심 소개로 바꾼 README 패치 미리보기
+    production:
+      format: diff
+      status: source-created
+      source-path: examples/readme-showcase/README.patch
+      source-hash: sha256:3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+    asset:
+      path: examples/readme-showcase/README.patch
+      provenance: examples/readme-showcase/provenance.yaml
+      source-run: runs/readme-harness/20260720-review-remediation
+      sha256: sha256:3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+      caption: 검토를 통과한 이전 README 실행의 실제 패치 일부입니다.
@@ -0,0 +1,78 @@
+schema-version: 1
+target:
+  repository: /home/donghyeon/workspace/ai-tool/readme-harness
+  readme-path: README.md
+mode: refresh
+profile-override: tool
+project-intent:
+  purpose: 저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안과 검토용 패치를 만드는 도구를 설명한다.
+  positioning: 사용자 경로를 먼저 보여 주고, 명령·경로·문장 근거 검사와 사람 작성 내용 보존은 필요한 수준에서만 설명한다.
+  maturity: 현재 Codex용 작성·검증 흐름을 지원하며 Claude와 Antigravity의 동일 동작은 아직 검증하지 않았다.
+audience:
+  primary:
+    - 저장소 README를 새로 만들거나 안전하게 갱신하려는 개발자
+  secondary:
+    - 하네스 검사와 프로파일을 확장하는 기여자
+reader-actions:
+  - 첫 두 문장에서 어떤 결과를 만드는 도구인지 판단한다.
+  - Codex에 README 작업을 요청하고 생성된 README와 패치를 확인한다.
+  - 작업 목적에 맞는 모드를 고른다.
+  - 검토한 패치만 명시적으로 적용한다.
+  - 개발 환경과 테스트 방법은 별도의 개발 절에서 찾는다.
+content-policy:
+  language: ko-KR
+  tone: 독자 행동을 먼저 밝히는 직접적인 기술 설명체
+  target-length: medium
+  preserve-existing-copy: true
+  detail-docs-policy: summary-and-link
+visual-policy:
+  mode: when-useful
+  max-visuals: 1
+  preferred-formats:
+    - diff
+  placeholder-format: HTML 주석 기반 제작 사양
+terminology-policy:
+  exact-identifiers: []
+  explain-on-first-use: {}
+  internal-only:
+    family: 작업 담당 방식
+    fan-out: 여러 담당자가 나눠 검토
+    collapse: 한 담당자가 맡아 처리
+    concrete worker: 실제 변경 담당자
+    verification family: 검증 담당 역할
+    route-to: 다시 작성할 지점
+public-surface-terms:
+  allowed:
+    - bootstrap
+    - audit
+    - refresh
+    - section-update
+    - readme-request.yaml
+    - README.generated.md
+    - README.patch
+    - requirement-driven-readme
+  explain-on-first-use: {}
+  docs-only:
+    - QUALITY_REVIEWED
+    - READY_FOR_APPLY
+    - claim-map.yaml
+    - visual-plan.yaml
+    - review-findings.yaml
+    - quality-manifest.yaml
+must-include:
+  - 한 문장 설명과 Codex 지원 범위
+  - 실제 검토를 통과한 패치 미리보기와 원본 파일 링크
+  - Codex 스킬 요청부터 생성 파일 확인, 성공 확인, 명시적 적용까지의 기본 사용자 경로
+  - bootstrap을 기본 경로로 두고 audit, refresh, section-update를 보조 경로로 설명
+  - 코드에서 확인한 사실, 사람 작성 내용 보존, 자동 적용 금지, 변경·비밀 값 차단 요약
+  - 사용자 입력과 생성 파일을 세 개에서 네 개 수준으로 요약
+  - 개발 환경 설치와 전체 테스트를 사용자 경로 뒤의 개발 절에 배치
+  - 아키텍처, 시각 자료, 상태, 사용량, 품질 비교 상세 문서 링크
+  - 현재 Codex 지원과 다른 도구의 동일 동작 미검증 한계
+must-exclude:
+  - 빠른 시작의 첫 행동으로 테스트나 개발 의존성 설치를 제시하는 구성
+  - 공개 README에서 내부 상태 이름, 내부 결과 파일, 게이트 계약을 설명하는 문장
+  - 저장소 근거 없는 성능·품질 우월성 주장
+  - 한 주장 마커가 여러 사실 문장을 덮는 구성
+  - 제품 결과보다 먼저 나오는 내부 구조도
+protected-sections: []
@@ -0,0 +1,7 @@
+{
+  "git-sha": "636617ccd9f20440f21339f808557c096b55fec2",
+  "dirty": true,
+  "diff-hash": "sha256:77b1a19a536615064a4894d23c78b2e7aa54a9ef4cf13bad194ae40565407951",
+  "scanned-at": null,
+  "file-count": 231
+}
@@ -0,0 +1,12 @@
+{
+  "schema-version": 1,
+  "run-id": "20260720-public-readme",
+  "repo-id": "readme-harness",
+  "mode": "refresh",
+  "target-repository": "/home/donghyeon/workspace/ai-tool/readme-harness",
+  "harness-version": "0.1.0",
+  "started-at": null,
+  "tool-adapter": "codex",
+  "input-hashes": {},
+  "usage": {}
+}
@@ -0,0 +1,38 @@
+{
+  "schema-version": 1,
+  "mode": "refresh",
+  "current": "REPOSITORY_SNAPSHOTTED",
+  "history": [
+    {
+      "state": "INITIALIZED"
+    },
+    {
+      "state": "INPUT_CAPTURED",
+      "gates": [
+        {
+          "name": "request",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        }
+      ]
+    },
+    {
+      "state": "REPOSITORY_SNAPSHOTTED",
+      "gates": [
+        {
+          "name": "snapshot",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "diff-hash": "sha256:77b1a19a536615064a4894d23c78b2e7aa54a9ef4cf13bad194ae40565407951"
+          }
+        }
+      ]
+    }
+  ],
+  "rework": {
+    "iterations": 0,
+    "findings": {}
+  }
+}
@@ -0,0 +1,224 @@
+# README Harness
+
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다. <!-- claim-id: C-PROJECT-001 -->
+
+- 새 README 작성
+- 기존 문서 점검
+- 사람 작성 영역을 보존한 갱신
+- 특정 섹션과 관련 검증 산출물의 재생성
+- 검토 후 별도로 실행하는 적용
+
+<!-- section-id: overview -->
+## 무엇을 만드는가
+
+README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다. <!-- claim-id: C-MODE-001 -->
+
+저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을
+넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인
+근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.
+<!-- claim-id: C-SAFETY-SUMMARY-001 -->
+
+결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며,
+다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
+<!-- claim-id: C-LIMIT-001 -->
+
+<!-- section-id: installation -->
+## 설치
+
+`Python` 3.12 이상이 필요합니다.
+런타임 의존성은 `jsonschema`와 `PyYAML`입니다.
+개발 의존성은 `pytest`입니다. <!-- claim-id: C-RUNTIME-001 -->
+
+저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다.
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지
+실행해 증명하지 않았습니다. <!-- claim-id: C-INSTALL-001 -->
+
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+먼저 전체 테스트를 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재
+README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다.
+
+자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새
+가상환경의 동일한 결과까지 보장하는 계약은 아닙니다. <!-- claim-id: C-TEST-COMMAND-001 -->
+
+이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서
+`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성
+역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사
+산출물을 준비합니다. <!-- claim-id: C-AUTHORING-001 -->
+
+대상 저장소용 실행 디렉터리를 만듭니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
+```
+
+이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.
+<!-- claim-id: C-INIT-001 -->
+
+실행 디렉터리에 `readme-request.yaml`, `repository-facts.yaml`, `readme-brief.yaml`,
+`readme-outline.yaml`, `README.candidate.md`, `claim-map.yaml`, `visual-plan.yaml`,
+`review-findings.yaml`이 준비되면 모든 결정론적 게이트를 재생합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 `QUALITY_REVIEWED`까지
+검증합니다. <!-- claim-id: C-BOOTSTRAP-001 -->
+
+<!-- section-id: usage -->
+## 사용 모드
+
+| 작업 | 모드 | 결과 |
+|---|---|---|
+| README가 없거나 전면 재작성 | `bootstrap` | 검증된 후보와 적용 준비용 패치 |
+| 기존 문서의 결함만 점검 | `audit` | 감사 결과와 검증 보고서, 후보·패치 없음 |
+| 사람 작성 영역을 보존한 갱신 | `refresh` | 3방향 병합과 병합본 전체 재검증 |
+| 한 섹션과 파급 산출물 갱신 | `section-update` | 관련 산출물 무효화 후 갱신 검증 재실행 |
+
+네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어
+있습니다. <!-- claim-id: C-USAGE-001 -->
+
+<!-- section-id: api -->
+## 요청 API, 설정과 산출물
+
+`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을
+정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은
+`runs/<repo-id>/<run-id>` 아래에서 격리합니다. <!-- claim-id: C-INPUT-001 -->
+
+어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지
+않은 값은 0으로 추정하지 않습니다. <!-- claim-id: C-USAGE-METRICS-001 -->
+
+대표 산출물은 다음 순서로 이어집니다.
+
+```text
+readme-brief.yaml + readme-outline.yaml
+README.candidate.md + claim-map.yaml + visual-plan.yaml
+prose-report.json + verification.json + review-findings.yaml
+quality-manifest.yaml
+README.generated.md + README.patch + apply-manifest.yaml
+```
+
+품질 검토를 통과한 뒤 다음 명령으로 패치를 준비합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+이 단계는 `README.generated.md`, `README.patch`, `apply-manifest.yaml`을 만들고
+상태를 `READY_FOR_APPLY`로 전진시킵니다. <!-- claim-id: C-PREPARE-001 -->
+
+검토가 끝난 패치만 별도 명령으로 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
+<!-- claim-id: C-APPLY-001 -->
+
+<!-- section-id: architecture -->
+## 동작 방식
+
+사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는
+근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적
+게이트와 독립 품질 심사를 통과해야 패치가 됩니다. <!-- claim-id: C-FLOW-001 -->
+
+```mermaid
+flowchart LR
+    T[Codex / Claude / Antigravity] --> O[실행 조정]
+    U[사용자 요구] --> P[독자 흐름·용어·그림 결정]
+    R[대상 저장소] --> E[근거 수집·프로젝트 분류]
+    O --> E
+    O --> P
+    E --> P
+    P --> W[README 작성]
+    P --> V[그림 소스·자산 생성]
+    W --> G[근거·명령·경로·문체 검사]
+    V --> G
+    G --> Q[독립 품질 심사]
+    Q -->|수정 필요| P
+    Q -->|통과| A[패치 준비·명시적 적용]
+    H[(해시 기반 실행 산출물)] --- E
+    H --- P
+    H --- G
+    H --- A
+```
+
+<!-- visual-id: harness-flow -->
+
+구성요소 책임과 컨텍스트 경계는 [아키텍처 문서](docs/architecture.md)에,
+모드별 전이는 [상태기계 문서](docs/state-machine.md)에 정리했습니다.
+
+<!-- section-id: safeguards -->
+## 안전장치
+
+- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.
+- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을
+  차단합니다. <!-- claim-id: C-TERM-001 -->
+- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이
+  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->
+- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,
+  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->
+- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로
+  전진합니다. <!-- claim-id: C-AUDIT-001 -->
+- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새
+  후보가 충돌하면 자동 적용을 막습니다. <!-- claim-id: C-MERGE-001 -->
+- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나
+  적용을 차단합니다. <!-- claim-id: C-APPLY-SAFETY-001 -->
+
+시각 자료의 소스·자산·대체 텍스트·신선도 규칙은
+[시각 자료 정책](docs/visuals.md)에서 확인할 수 있습니다.
+
+<!-- section-id: tests -->
+## 테스트
+
+전체 회귀 테스트는 다음 명령으로 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은
+Python 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행
+경로, Mermaid 그림 결정을 확인합니다. <!-- claim-id: C-CI-001 -->
+
+<!-- section-id: documentation -->
+## 상세 문서
+
+- [구성요소와 컨텍스트 경계](docs/architecture.md)
+- [그림 결정과 소스·자산 계약](docs/visuals.md)
+- [모드별 상태와 차단 조건](docs/state-machine.md)
+- [모델 사용량 계측](docs/usage-metrics.md)
+- [블라인드 README 품질 벤치마크](docs/quality-benchmark.md)
+- [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 스키마·규칙·워크플로는 `.agents`, 테스트는
+`tests`에 있습니다. <!-- claim-id: C-LAYOUT-001 -->
+
+<!-- section-id: limitations -->
+## 현재 한계
+
+- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된
+  산출물을 검증하고 상태를 전진시킵니다.
+- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증
+  목표입니다. <!-- claim-id: C-LIMIT-002 -->
+- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은
+  명령은 실제 실행 성공을 뜻하지 않습니다. <!-- claim-id: C-VERIFY-LIMIT-001 -->
+- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다.
+  `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다. <!-- claim-id: C-BENCH-LIMIT-001 -->
@@ -0,0 +1,224 @@
+# README Harness
+
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다. <!-- claim-id: C-PROJECT-001 -->
+
+- 새 README 작성
+- 기존 문서 점검
+- 사람 작성 영역을 보존한 갱신
+- 특정 섹션과 관련 검증 산출물의 재생성
+- 검토 후 별도로 실행하는 적용
+
+<!-- section-id: overview -->
+## 무엇을 만드는가
+
+README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다. <!-- claim-id: C-MODE-001 -->
+
+저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을
+넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인
+근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.
+<!-- claim-id: C-SAFETY-SUMMARY-001 -->
+
+결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며,
+다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
+<!-- claim-id: C-LIMIT-001 -->
+
+<!-- section-id: installation -->
+## 설치
+
+`Python` 3.12 이상이 필요합니다.
+런타임 의존성은 `jsonschema`와 `PyYAML`입니다.
+개발 의존성은 `pytest`입니다. <!-- claim-id: C-RUNTIME-001 -->
+
+저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다.
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지
+실행해 증명하지 않았습니다. <!-- claim-id: C-INSTALL-001 -->
+
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+먼저 전체 테스트를 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재
+README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다.
+
+자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새
+가상환경의 동일한 결과까지 보장하는 계약은 아닙니다. <!-- claim-id: C-TEST-COMMAND-001 -->
+
+이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서
+`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성
+역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사
+산출물을 준비합니다. <!-- claim-id: C-AUTHORING-001 -->
+
+대상 저장소용 실행 디렉터리를 만듭니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
+```
+
+이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.
+<!-- claim-id: C-INIT-001 -->
+
+실행 디렉터리에 `readme-request.yaml`, `repository-facts.yaml`, `readme-brief.yaml`,
+`readme-outline.yaml`, `README.candidate.md`, `claim-map.yaml`, `visual-plan.yaml`,
+`review-findings.yaml`이 준비되면 모든 결정론적 게이트를 재생합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 `QUALITY_REVIEWED`까지
+검증합니다. <!-- claim-id: C-BOOTSTRAP-001 -->
+
+<!-- section-id: usage -->
+## 사용 모드
+
+| 작업 | 모드 | 결과 |
+|---|---|---|
+| README가 없거나 전면 재작성 | `bootstrap` | 검증된 후보와 적용 준비용 패치 |
+| 기존 문서의 결함만 점검 | `audit` | 감사 결과와 검증 보고서, 후보·패치 없음 |
+| 사람 작성 영역을 보존한 갱신 | `refresh` | 3방향 병합과 병합본 전체 재검증 |
+| 한 섹션과 파급 산출물 갱신 | `section-update` | 관련 산출물 무효화 후 갱신 검증 재실행 |
+
+네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어
+있습니다. <!-- claim-id: C-USAGE-001 -->
+
+<!-- section-id: api -->
+## 요청 API, 설정과 산출물
+
+`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을
+정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은
+`runs/<repo-id>/<run-id>` 아래에서 격리합니다. <!-- claim-id: C-INPUT-001 -->
+
+어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지
+않은 값은 0으로 추정하지 않습니다. <!-- claim-id: C-USAGE-METRICS-001 -->
+
+대표 산출물은 다음 순서로 이어집니다.
+
+```text
+readme-brief.yaml + readme-outline.yaml
+README.candidate.md + claim-map.yaml + visual-plan.yaml
+prose-report.json + verification.json + review-findings.yaml
+quality-manifest.yaml
+README.generated.md + README.patch + apply-manifest.yaml
+```
+
+품질 검토를 통과한 뒤 다음 명령으로 패치를 준비합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+이 단계는 `README.generated.md`, `README.patch`, `apply-manifest.yaml`을 만들고
+상태를 `READY_FOR_APPLY`로 전진시킵니다. <!-- claim-id: C-PREPARE-001 -->
+
+검토가 끝난 패치만 별도 명령으로 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
+<!-- claim-id: C-APPLY-001 -->
+
+<!-- section-id: architecture -->
+## 동작 방식
+
+사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는
+근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적
+게이트와 독립 품질 심사를 통과해야 패치가 됩니다. <!-- claim-id: C-FLOW-001 -->
+
+```mermaid
+flowchart LR
+    T[Codex / Claude / Antigravity] --> O[실행 조정]
+    U[사용자 요구] --> P[독자 흐름·용어·그림 결정]
+    R[대상 저장소] --> E[근거 수집·프로젝트 분류]
+    O --> E
+    O --> P
+    E --> P
+    P --> W[README 작성]
+    P --> V[그림 소스·자산 생성]
+    W --> G[근거·명령·경로·문체 검사]
+    V --> G
+    G --> Q[독립 품질 심사]
+    Q -->|수정 필요| P
+    Q -->|통과| A[패치 준비·명시적 적용]
+    H[(해시 기반 실행 산출물)] --- E
+    H --- P
+    H --- G
+    H --- A
+```
+
+<!-- visual-id: harness-flow -->
+
+구성요소 책임과 컨텍스트 경계는 [아키텍처 문서](docs/architecture.md)에,
+모드별 전이는 [상태기계 문서](docs/state-machine.md)에 정리했습니다.
+
+<!-- section-id: safeguards -->
+## 안전장치
+
+- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.
+- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을
+  차단합니다. <!-- claim-id: C-TERM-001 -->
+- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이
+  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->
+- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,
+  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->
+- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로
+  전진합니다. <!-- claim-id: C-AUDIT-001 -->
+- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새
+  후보가 충돌하면 자동 적용을 막습니다. <!-- claim-id: C-MERGE-001 -->
+- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나
+  적용을 차단합니다. <!-- claim-id: C-APPLY-SAFETY-001 -->
+
+시각 자료의 소스·자산·대체 텍스트·신선도 규칙은
+[시각 자료 정책](docs/visuals.md)에서 확인할 수 있습니다.
+
+<!-- section-id: tests -->
+## 테스트
+
+전체 회귀 테스트는 다음 명령으로 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은
+Python 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행
+경로, Mermaid 그림 결정을 확인합니다. <!-- claim-id: C-CI-001 -->
+
+<!-- section-id: documentation -->
+## 상세 문서
+
+- [구성요소와 컨텍스트 경계](docs/architecture.md)
+- [그림 결정과 소스·자산 계약](docs/visuals.md)
+- [모드별 상태와 차단 조건](docs/state-machine.md)
+- [모델 사용량 계측](docs/usage-metrics.md)
+- [블라인드 README 품질 벤치마크](docs/quality-benchmark.md)
+- [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 스키마·규칙·워크플로는 `.agents`, 테스트는
+`tests`에 있습니다. <!-- claim-id: C-LAYOUT-001 -->
+
+<!-- section-id: limitations -->
+## 현재 한계
+
+- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된
+  산출물을 검증하고 상태를 전진시킵니다.
+- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증
+  목표입니다. <!-- claim-id: C-LIMIT-002 -->
+- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은
+  명령은 실제 실행 성공을 뜻하지 않습니다. <!-- claim-id: C-VERIFY-LIMIT-001 -->
+- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다.
+  `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다. <!-- claim-id: C-BENCH-LIMIT-001 -->
@@ -0,0 +1,295 @@
+--- README.md (current)
+++ README.md (candidate)
+@@ -1,77 +1,224 @@
+ # README Harness
+ 
+-A GitHub-README-specialized harness built around a shared core with entrypoints
+-for **Codex**, **Antigravity**, and **Claude**. It does not "prettify" READMEs —
+-it analyzes the facts that exist in a repository, judges project type and
+-audience, then iteratively produces and maintains a README with a readable
+-structure, verified run instructions, and planned (not decorative) visuals.
+-
+-> **Status:** `bootstrap`, `audit`, `refresh`, and `section-update` have
+-> deterministic Codex-path drivers and gates. The repository does **not** yet
+-> claim Claude/Antigravity runtime equivalence; that remains the Phase 4
+-> conformance goal.
+-
+-## Core idea
+-
+-Two authority sources: the **repository** (technical facts, always
+-evidence-backed) and **`readme-request.yaml`** (why the project exists, audience,
+-language, length, what to preserve). Every state transition is blocked by a
+-deterministic gate script. High-risk factual claims—commands, versions,
+-prerequisites, modules, dependency directions, endpoints, guarantees, and
+-limitations—are traced to repository facts via `claim-map.yaml`.
+-
+-## Layout
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다. <!-- claim-id: C-PROJECT-001 -->
+
+- 새 README 작성
+- 기존 문서 점검
+- 사람 작성 영역을 보존한 갱신
+- 특정 섹션과 관련 검증 산출물의 재생성
+- 검토 후 별도로 실행하는 적용
+
+<!-- section-id: overview -->
+## 무엇을 만드는가
+
+README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다. <!-- claim-id: C-MODE-001 -->
+
+저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을
+넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인
+근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.
+<!-- claim-id: C-SAFETY-SUMMARY-001 -->
+
+결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며,
+다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
+<!-- claim-id: C-LIMIT-001 -->
+
+<!-- section-id: installation -->
+## 설치
+
+`Python` 3.12 이상이 필요합니다.
+런타임 의존성은 `jsonschema`와 `PyYAML`입니다.
+개발 의존성은 `pytest`입니다. <!-- claim-id: C-RUNTIME-001 -->
+
+저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다.
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지
+실행해 증명하지 않았습니다. <!-- claim-id: C-INSTALL-001 -->
+
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+먼저 전체 테스트를 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재
+README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다.
+
+자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새
+가상환경의 동일한 결과까지 보장하는 계약은 아닙니다. <!-- claim-id: C-TEST-COMMAND-001 -->
+
+이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서
+`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성
+역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사
+산출물을 준비합니다. <!-- claim-id: C-AUTHORING-001 -->
+
+대상 저장소용 실행 디렉터리를 만듭니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
+```
+
+이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.
+<!-- claim-id: C-INIT-001 -->
+
+실행 디렉터리에 `readme-request.yaml`, `repository-facts.yaml`, `readme-brief.yaml`,
+`readme-outline.yaml`, `README.candidate.md`, `claim-map.yaml`, `visual-plan.yaml`,
+`review-findings.yaml`이 준비되면 모든 결정론적 게이트를 재생합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 `QUALITY_REVIEWED`까지
+검증합니다. <!-- claim-id: C-BOOTSTRAP-001 -->
+
+<!-- section-id: usage -->
+## 사용 모드
+
+| 작업 | 모드 | 결과 |
+|---|---|---|
+| README가 없거나 전면 재작성 | `bootstrap` | 검증된 후보와 적용 준비용 패치 |
+| 기존 문서의 결함만 점검 | `audit` | 감사 결과와 검증 보고서, 후보·패치 없음 |
+| 사람 작성 영역을 보존한 갱신 | `refresh` | 3방향 병합과 병합본 전체 재검증 |
+| 한 섹션과 파급 산출물 갱신 | `section-update` | 관련 산출물 무효화 후 갱신 검증 재실행 |
+
+네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어
+있습니다. <!-- claim-id: C-USAGE-001 -->
+
+<!-- section-id: api -->
+## 요청 API, 설정과 산출물
+
+`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을
+정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은
+`runs/<repo-id>/<run-id>` 아래에서 격리합니다. <!-- claim-id: C-INPUT-001 -->
+
+어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지
+않은 값은 0으로 추정하지 않습니다. <!-- claim-id: C-USAGE-METRICS-001 -->
+
+대표 산출물은 다음 순서로 이어집니다.
+ 
+ ```text
+-.agents/                     portable core shared by all three tools
+-  skills/requirement-driven-readme/{SKILL.md,references/,scripts/}
+-  workflows/  profiles/  schemas/  rules/  rubrics/  templates/  adapters/
+-AGENTS.md / GEMINI.md / CLAUDE.md   thin tool entrypoints
+-.codex/ .claude/             tool-native subagents & config
+-src/readme_harness/          deterministic gate logic (Python)
+-runs/<repo-id>/<run-id>/     per-run artifacts (git-ignored)
+-```
+-
+-## Modes
+-
+-`bootstrap` · `refresh` · `audit` · `section-update` are implemented. Candidate
+-authoring remains an LLM role; state transitions, merge/apply safety, and
+-verification are deterministic.
+-
+-```bash
+-# Claude
+-/readme-harness bootstrap
+-# Codex / Antigravity: follow AGENTS.md / GEMINI.md
+-```
+-
+-## State machine
+-
+-`INITIALIZED → INPUT_CAPTURED → REPOSITORY_SNAPSHOTTED → FACTS_EXTRACTED →
+-PROJECT_PROFILED → README_PLANNED → README_DRAFTED → VISUALS_PLANNED →
+-STRUCTURALLY_VALIDATED → TECHNICALLY_VERIFIED → QUALITY_REVIEWED →
+-READY_FOR_APPLY → APPLIED`
+-
+-`READY_FOR_APPLY` writes `README.generated.md` + `README.patch`; applying to the
+-target README is an explicit step. The reviewed candidate is sealed in
+-`quality-manifest.yaml`; apply rechecks repository freshness, target and
+-generated hashes, and path containment through `apply-manifest.yaml`.
+-
+-After the logical roles have authored the run artifacts, the bootstrap gates
+-can be replayed as one deterministic command:
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py \
+-  --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+-```
+-
+-The driver stops at `QUALITY_REVIEWED`. `generate_patch.py` prepares the sealed
+-candidate, and `apply_patch.py` is the separate explicit apply step.
+-
+-## Development
+readme-brief.yaml + readme-outline.yaml
+README.candidate.md + claim-map.yaml + visual-plan.yaml
+prose-report.json + verification.json + review-findings.yaml
+quality-manifest.yaml
+README.generated.md + README.patch + apply-manifest.yaml
+```
+
+품질 검토를 통과한 뒤 다음 명령으로 패치를 준비합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+이 단계는 `README.generated.md`, `README.patch`, `apply-manifest.yaml`을 만들고
+상태를 `READY_FOR_APPLY`로 전진시킵니다. <!-- claim-id: C-PREPARE-001 -->
+
+검토가 끝난 패치만 별도 명령으로 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
+```
+
+적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
+<!-- claim-id: C-APPLY-001 -->
+
+<!-- section-id: architecture -->
+## 동작 방식
+
+사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는
+근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적
+게이트와 독립 품질 심사를 통과해야 패치가 됩니다. <!-- claim-id: C-FLOW-001 -->
+
+```mermaid
+flowchart LR
+    T[Codex / Claude / Antigravity] --> O[실행 조정]
+    U[사용자 요구] --> P[독자 흐름·용어·그림 결정]
+    R[대상 저장소] --> E[근거 수집·프로젝트 분류]
+    O --> E
+    O --> P
+    E --> P
+    P --> W[README 작성]
+    P --> V[그림 소스·자산 생성]
+    W --> G[근거·명령·경로·문체 검사]
+    V --> G
+    G --> Q[독립 품질 심사]
+    Q -->|수정 필요| P
+    Q -->|통과| A[패치 준비·명시적 적용]
+    H[(해시 기반 실행 산출물)] --- E
+    H --- P
+    H --- G
+    H --- A
+```
+
+<!-- visual-id: harness-flow -->
+
+구성요소 책임과 컨텍스트 경계는 [아키텍처 문서](docs/architecture.md)에,
+모드별 전이는 [상태기계 문서](docs/state-machine.md)에 정리했습니다.
+
+<!-- section-id: safeguards -->
+## 안전장치
+
+- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.
+- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을
+  차단합니다. <!-- claim-id: C-TERM-001 -->
+- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이
+  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->
+- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,
+  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->
+- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로
+  전진합니다. <!-- claim-id: C-AUDIT-001 -->
+- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새
+  후보가 충돌하면 자동 적용을 막습니다. <!-- claim-id: C-MERGE-001 -->
+- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나
+  적용을 차단합니다. <!-- claim-id: C-APPLY-SAFETY-001 -->
+
+시각 자료의 소스·자산·대체 텍스트·신선도 규칙은
+[시각 자료 정책](docs/visuals.md)에서 확인할 수 있습니다.
+
+<!-- section-id: tests -->
+## 테스트
+
+전체 회귀 테스트는 다음 명령으로 실행합니다.
+ 
+ ```bash
+ python3 -m pytest -q
+ ```
+ 
+-Design spec: `docs/superpowers/specs/2026-07-16-readme-harness-design.md`.
+-Phase 1 plan: `docs/superpowers/plans/2026-07-16-readme-harness-phase1.md`.
+GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은
+Python 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행
+경로, Mermaid 그림 결정을 확인합니다. <!-- claim-id: C-CI-001 -->
+
+<!-- section-id: documentation -->
+## 상세 문서
+
+- [구성요소와 컨텍스트 경계](docs/architecture.md)
+- [그림 결정과 소스·자산 계약](docs/visuals.md)
+- [모드별 상태와 차단 조건](docs/state-machine.md)
+- [모델 사용량 계측](docs/usage-metrics.md)
+- [블라인드 README 품질 벤치마크](docs/quality-benchmark.md)
+- [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 스키마·규칙·워크플로는 `.agents`, 테스트는
+`tests`에 있습니다. <!-- claim-id: C-LAYOUT-001 -->
+
+<!-- section-id: limitations -->
+## 현재 한계
+
+- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된
+  산출물을 검증하고 상태를 전진시킵니다.
+- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증
+  목표입니다. <!-- claim-id: C-LIMIT-002 -->
+- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은
+  명령은 실제 실행 성공을 뜻하지 않습니다. <!-- claim-id: C-VERIFY-LIMIT-001 -->
+- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다.
+  `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다. <!-- claim-id: C-BENCH-LIMIT-001 -->
@@ -0,0 +1,7 @@
+schema-version: 1
+mode: bootstrap
+target-rel: README.md
+generated-hash: sha256:dd241b6b8b7a0972086226c73b217128d98224cf30ab87505a6d5e8e0d2dcedf
+target-before-hash: sha256:53b671528d4f99b6e806145e7b687b61a5a443ceffb1fd225059f92fdc50c456
+repository-snapshot-hash: sha256:8ea3e3693ce644a2576f9a8670088a36e5964ac8edaca5b279f7281e44aa428b
+review-score: 90
@@ -0,0 +1,160 @@
+schema-version: 1
+claims:
+  - id: C-PROJECT-001
+    type: factual
+    statement: 명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
+    section: overview
+    sources: [{fact-id: F-PROJECT-001}]
+    status: supported
+  - id: C-MODE-001
+    type: factual
+    statement: '`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다.'
+    section: overview
+    sources: [{fact-id: F-MODE-001}]
+    status: supported
+  - id: C-SAFETY-SUMMARY-001
+    type: factual
+    statement: '패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.'
+    section: overview
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-LIMIT-001
+    type: factual
+    statement: 다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
+    section: overview
+    sources: [{fact-id: F-TOOL-001}, {fact-id: F-LIMIT-001}]
+    status: supported
+  - id: C-RUNTIME-001
+    type: factual
+    section: installation
+    sources: [{fact-id: F-RUNTIME-001}, {fact-id: F-DEPENDENCY-001}]
+    status: supported
+  - id: C-INSTALL-001
+    type: factual
+    statement: 실행해 증명하지 않았습니다.
+    section: installation
+    sources: [{fact-id: F-DEPENDENCY-001}]
+    status: supported
+  - id: C-TEST-COMMAND-001
+    type: factual
+    statement: 가상환경의 동일한 결과까지 보장하는 계약은 아닙니다.
+    section: quick-start
+    sources: [{fact-id: F-SELF-README-001}, {fact-id: F-LIMIT-001}]
+    status: supported
+  - id: C-AUTHORING-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-AUTHORING-001}, {fact-id: F-DRIVER-001}]
+    status: supported
+  - id: C-INIT-001
+    type: factual
+    statement: '이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.'
+    section: quick-start
+    sources: [{fact-id: F-DRIVER-001}]
+    status: supported
+  - id: C-BOOTSTRAP-001
+    type: factual
+    statement: 검증합니다.
+    section: quick-start
+    sources: [{fact-id: F-DRIVER-001}, {fact-id: F-STATE-001}]
+    status: supported
+  - id: C-USAGE-001
+    type: factual
+    statement: 네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어
+    section: usage
+    sources: [{fact-id: F-MODE-001}, {fact-id: F-STATE-001}]
+    status: supported
+  - id: C-INPUT-001
+    type: factual
+    statement: '`runs/<repo-id>/<run-id>` 아래에서 격리합니다.'
+    section: api
+    sources: [{fact-id: F-ARTIFACT-001}, {fact-id: F-LAYOUT-001}]
+    status: supported
+  - id: C-USAGE-METRICS-001
+    type: factual
+    section: api
+    sources: [{fact-id: F-USAGE-001}]
+    status: supported
+  - id: C-PREPARE-001
+    type: factual
+    statement: '상태를 `READY_FOR_APPLY`로 전진시킵니다.'
+    section: api
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-APPLY-001
+    type: factual
+    statement: 적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
+    section: api
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-FLOW-001
+    type: factual
+    statement: 게이트와 독립 품질 심사를 통과해야 패치가 됩니다.
+    section: architecture
+    sources: [{fact-id: F-STATE-001}, {fact-id: F-REVIEW-001}, {fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-TERM-001
+    type: factual
+    statement: 차단합니다.
+    section: safeguards
+    sources: [{fact-id: F-TERM-001}]
+    status: supported
+  - id: C-VISUAL-001
+    type: factual
+    statement: 일치해야 시각 자료 게이트를 통과합니다.
+    section: safeguards
+    sources: [{fact-id: F-VISUAL-001}]
+    status: supported
+  - id: C-REVIEW-001
+    type: factual
+    statement: '`review.md`는 검증된 YAML에서 렌더링합니다.'
+    section: safeguards
+    sources: [{fact-id: F-REVIEW-001}]
+    status: supported
+  - id: C-AUDIT-001
+    type: factual
+    statement: 전진합니다.
+    section: safeguards
+    sources: [{fact-id: F-AUDIT-001}]
+    status: supported
+  - id: C-MERGE-001
+    type: factual
+    statement: 후보가 충돌하면 자동 적용을 막습니다.
+    section: safeguards
+    sources: [{fact-id: F-MERGE-001}]
+    status: supported
+  - id: C-APPLY-SAFETY-001
+    type: factual
+    statement: 적용을 차단합니다.
+    section: safeguards
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-CI-001
+    type: factual
+    statement: 경로, Mermaid 그림 결정을 확인합니다.
+    section: tests
+    sources: [{fact-id: F-CI-001}, {fact-id: F-SELF-README-001}]
+    status: supported
+  - id: C-LAYOUT-001
+    type: factual
+    statement: '`tests`에 있습니다.'
+    section: documentation
+    sources: [{fact-id: F-LAYOUT-001}]
+    status: supported
+  - id: C-LIMIT-002
+    type: factual
+    statement: 목표입니다.
+    section: limitations
+    sources: [{fact-id: F-TOOL-001}, {fact-id: F-LIMIT-001}]
+    status: supported
+  - id: C-VERIFY-LIMIT-001
+    type: factual
+    statement: 명령은 실제 실행 성공을 뜻하지 않습니다.
+    section: limitations
+    sources: [{fact-id: F-LIMIT-001}]
+    status: supported
+  - id: C-BENCH-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-BENCH-001}]
+    status: supported
@@ -0,0 +1,31 @@
+{
+  "schema-version": 1,
+  "policy-id": "korean-reader-prose-v1",
+  "language": "ko-KR",
+  "applicable": true,
+  "scope": "candidate",
+  "state": "PASS_WITH_WARNINGS",
+  "summary": {
+    "errors": 0,
+    "warnings": 1,
+    "sentences": 108,
+    "prose-characters": 2081,
+    "hangul-characters": 1839
+  },
+  "findings": [
+    {
+      "rule-id": "KO-REPEATED-ENDING",
+      "severity": "warning",
+      "line": 4,
+      "section": "README Harness",
+      "region-kind": "candidate",
+      "excerpt": "합니다 (29/43문장)",
+      "message": "같은 문장 종결이 이어져 설명이 기계적으로 들릴 수 있습니다.",
+      "suggestion": "정의, 절차, 제한에 맞춰 현재형 동사와 명사형 표제를 섞어 쓰세요.",
+      "source-ids": [
+        "NIKL-EASY-PUBLIC-LANGUAGE"
+      ],
+      "id": "P-001"
+    }
+  ]
+}
@@ -0,0 +1,14 @@
+schema-version: 2
+mode: bootstrap
+profile: library
+repository-snapshot-hash: sha256:8ea3e3693ce644a2576f9a8670088a36e5964ac8edaca5b279f7281e44aa428b
+artifacts:
+  readme-request.yaml: sha256:5aaa41c2d4131ea1587660751c73b6a92894c684737fb3315de44dd210e03a0f
+  repository-facts.yaml: sha256:61f1fb4b892ca6b21ad4a54634e687f2e231d1582315ff37bda31b28e4a68735
+  readme-brief.yaml: sha256:a17a7877ee3799ddd9e240f75fd59f285f79d8f95364c701f61fa0b280f89529
+  readme-outline.yaml: sha256:9748f1e59bfb884044e685970f319fca3e54c8b7b1cdad7861993cd15cf0e57b
+  README.candidate.md: sha256:dd241b6b8b7a0972086226c73b217128d98224cf30ab87505a6d5e8e0d2dcedf
+  claim-map.yaml: sha256:886526bb672493d1846270540b422858f2a68985b2be5c79cdddd8a285e77ee6
+  visual-plan.yaml: sha256:8e610350b341ce517de9a39746f83c62f0e97197916d41b3f857e67c4ce153d7
+  prose-report.json: sha256:6c34d9c7d068786688dea529478b5a88ef2017b05d772b45c32374f1888a17fb
+  review-findings.yaml: sha256:6d19d78927d7255f39ef7fb3f859dca715d2128ed1b96ab5bad3d65bc8aeaa32
@@ -0,0 +1,47 @@
+schema-version: 1
+project-profile:
+  primary: library
+  secondary: [documentation-tooling]
+audiences:
+  primary:
+    - 저장소 README를 만들거나 갱신하는 개발자
+  secondary:
+    - 결정론적 게이트와 도구 어댑터를 확장하는 기여자
+reader-outcomes:
+  - 프로젝트가 만드는 결과와 안전 경계를 30초 안에 설명한다.
+  - 의존성을 설치하고 전체 테스트로 개발 환경을 확인한다.
+  - 네 가지 모드 중 자기 작업에 맞는 경로를 선택한다.
+  - 후보를 검증하고 패치를 준비한 뒤 명시적으로 적용한다.
+project-story:
+  value-proposition: 저장소 코드와 사용자 요구를 근거로 README 후보를 만들고 검증 가능한 패치로 전달한다.
+  problem: README 자동 작성은 실행 명령과 구조 설명이 실제 저장소와 어긋나거나 기존 문서를 훼손하기 쉽다.
+  target-reader: README를 새로 만들거나 안전하게 갱신하려는 개발자
+  notable-traits:
+    - text: 저장소 사실과 사용자 의도를 분리하고 고위험 주장을 근거에 연결한다.
+      fact-ids: [F-PROJECT-001, F-STATE-001]
+    - text: 포함한 그림은 개요 결정부터 실제 소스 또는 자산까지 교차 검증한다.
+      fact-ids: [F-VISUAL-001]
+    - text: 품질 심사 근거는 실제 README 줄 범위와 해시에 묶인다.
+      fact-ids: [F-REVIEW-001]
+    - text: 패치 준비와 대상 README 적용이 분리되고 적용 직전에 상태와 해시를 다시 검사한다.
+      fact-ids: [F-APPLY-001]
+  maturity: Codex 경로의 네 모드 드라이버는 구현됐으나 후보 작성은 LLM 경계에 있고 도구 간 동등성은 아직 검증하지 않았다.
+  limitations:
+    - 후보 작성 자체는 결정론적 코드가 아니라 LLM 파이프라인이 담당한다.
+    - Claude와 Antigravity의 런타임 동등성은 Phase 4 전에는 주장하지 않는다.
+narrative-variant: library
+reader-journey:
+  - reader-question: 무엇을 만들고 어떤 문제를 막습니까?
+    section-id: overview
+  - reader-question: 로컬에서 설치와 테스트를 어떻게 확인합니까?
+    section-id: quick-start
+  - reader-question: 내 작업에는 어떤 모드를 선택해야 합니까?
+    section-id: usage
+  - reader-question: 저장소 분석부터 적용까지 어떤 흐름으로 동작합니까?
+    section-id: architecture
+  - reader-question: 어떤 오류와 문서 훼손을 차단합니까?
+    section-id: safeguards
+  - reader-question: 기여 전에 무엇을 검증해야 합니까?
+    section-id: tests
+  - reader-question: 상세 계약은 어디에서 확인합니까?
+    section-id: documentation
@@ -0,0 +1,129 @@
+schema-version: 1
+sections:
+  - id: overview
+    title-guidance: 무엇을 만드는가
+    level: 2
+    purpose: 프로젝트의 결과, 대상 독자, 사실 근거와 명시적 적용이라는 핵심 경계를 첫 화면에서 설명한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 저장소 사실과 사용자 요구를 바탕으로 README 후보와 패치를 만든다는 한 문장 정의
+      - bootstrap, audit, refresh, section-update 네 작업 결과
+      - 후보 작성은 LLM 경계이고 도구 간 동등성을 아직 주장하지 않는다는 제한
+    visual-slot:
+      decision: exclude
+      reader-question: 프로젝트 정체성을 이해하는 데 그림이 필요한가?
+      rationale: 결과와 안전 경계는 짧은 정의와 목록으로 더 직접적으로 전달된다.
+  - id: installation
+    title-guidance: 설치
+    level: 2
+    purpose: 필요한 Python 버전과 개발 의존성 설치 명령을 제시한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - Python 3.12 이상
+      - editable 개발 설치 명령
+  - id: quick-start
+    title-guidance: 빠른 시작
+    level: 2
+    purpose: 설치 후 전체 테스트를 실행하고 첫 bootstrap run을 초기화하는 최소 경로를 제공한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 테스트 명령과 통과 신호
+      - init_run 명령과 생성 위치
+      - 독립형 생성 CLI가 아니라 Codex 스킬 요청으로 작성 산출물을 준비한다는 경계
+      - 준비해야 할 작성 산출물과 run_bootstrap으로 게이트를 재생하는 조건
+    visual-slot:
+      decision: exclude
+      reader-question: 세 개의 순차 명령을 이해하는 데 그림이 필요한가?
+      rationale: 복사 가능한 명령과 각 성공 신호가 그림보다 정확하다.
+  - id: usage
+    title-guidance: 사용 모드
+    level: 2
+    purpose: 독자 작업을 기준으로 네 가지 모드의 선택 조건과 결과를 구분한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 새 문서 작성, 기존 문서 점검, 안전 갱신, 부분 갱신의 선택 기준
+      - audit은 후보나 패치를 만들지 않는다는 차이
+  - id: api
+    title-guidance: 요청 API, 설정과 산출물
+    level: 2
+    purpose: 사용자 의도 파일, 실행 디렉터리, 후보·검증·패치 산출물의 대응을 설명한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - readme-request의 역할
+      - runs 경로와 주요 산출물
+      - 어댑터 제공 모델 사용량과 미제공 값 비추정 원칙
+      - patch 준비와 apply 명령의 분리
+  - id: architecture
+    title-guidance: 동작 방식
+    level: 2
+    purpose: 사용자 요구와 저장소 근거가 계획·작성·시각화·게이트·품질 심사·적용으로 흐르는 구조를 한 화면에서 설명한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 의미 판단과 결정론적 검증의 경계
+      - 실패 시 계획 단계로 돌아가는 재작업 흐름
+      - 해시 기반 산출물 저장소
+    visual-slot:
+      decision: include
+      reader-question: 저장소 근거와 사용자 요구가 어떻게 검토 가능한 패치로 변합니까?
+      rationale: 두 입력이 계획에서 합쳐지고 작성과 그림이 검증으로 모인 뒤 품질 심사에서 재작업 또는 적용으로 갈라지는 관계는 산문보다 흐름도가 빠르다.
+      purpose: 저장소 분석부터 독립 품질 심사와 명시적 적용까지의 데이터 흐름과 재작업 경계를 보여준다.
+  - id: safeguards
+    title-guidance: 안전장치
+    level: 2
+    purpose: 사실·명령·경로·비밀 값·시각 자료·품질 근거·보호 영역·적용 경계를 구체적으로 설명한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 근거 없는 고위험 주장 차단
+      - 공개 용어와 그림 완성도 계약
+      - 감사 산출물 검증과 갱신 보호 영역
+      - 패치 준비 후 별도 apply
+  - id: tests
+    title-guidance: 테스트
+    level: 2
+    purpose: 전체 회귀 테스트 명령과 자체 README 품질 계약을 설명한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 전체 pytest 명령
+      - CI가 같은 명령을 실행한다는 사실
+      - 자체 README 독자 과업과 시각 결정 테스트
+  - id: documentation
+    title-guidance: 상세 문서
+    level: 2
+    purpose: 아키텍처, 시각 자료, 상태기계, 설계 명세로 독자를 안내한다.
+    required: true
+    content-strategy: summary-link
+    target-doc: docs/
+    content-requirements:
+      - architecture.md
+      - visuals.md
+      - state-machine.md
+      - usage-metrics.md
+      - quality-benchmark.md
+      - 설계 명세
+  - id: limitations
+    title-guidance: 현재 한계
+    level: 2
+    purpose: 결정론 게이트와 LLM 후보 작성의 경계, 도구 간 동등성 미검증 상태를 명시한다.
+    required: true
+    content-strategy: inline
+    target-doc: null
+    content-requirements:
+      - 후보 작성은 LLM 파이프라인
+      - cross-tool equivalence는 Phase 4 목표
+      - 블라인드 품질 비교는 아직 not-run이며 PASS 전 우월성 주장 금지
@@ -0,0 +1,57 @@
+schema-version: 1
+target:
+  repository: /home/donghyeon/workspace/ai-tool/readme-harness
+  readme-path: README.md
+mode: bootstrap
+profile-override: library
+project-intent:
+  purpose: 저장소의 실제 코드와 사용자 요구를 바탕으로 검증 가능한 README 후보와 명시적으로 적용할 패치를 만드는 하네스를 설명한다.
+  positioning: 사실 추적과 적용 안전성뿐 아니라 독자 과업, 공개 용어, 실제 시각 자료, 근거가 고정된 품질 심사를 함께 다루는 README 제작 도구다.
+  maturity: Codex 경로의 bootstrap, audit, refresh, section-update는 구현됐고 도구 간 런타임 동등성은 아직 주장하지 않는다.
+audience:
+  primary:
+    - 저장소 README를 새로 만들거나 안전하게 갱신하려는 개발자
+  secondary:
+    - 하네스의 게이트와 워크플로를 확장하는 기여자
+reader-actions:
+  - 이 프로젝트가 어떤 결과를 만들고 무엇을 보장하는지 30초 안에 판단한다.
+  - 개발 환경을 준비하고 전체 테스트를 실행해 설치 상태를 확인한다.
+  - 작업에 맞는 bootstrap, audit, refresh, section-update 모드를 고른다.
+  - 생성된 패치를 검토한 뒤 별도의 명시적 적용 단계를 실행한다.
+content-policy:
+  language: ko-KR
+  tone: 직접적이고 검증 수준을 분명히 밝히는 기술 설명체
+  target-length: medium
+  preserve-existing-copy: false
+  detail-docs-policy: summary-and-link
+visual-policy:
+  mode: when-useful
+  max-visuals: 1
+  preferred-formats:
+    - mermaid
+  placeholder-format: HTML 주석 기반 제작 사양
+terminology-policy:
+  exact-identifiers: []
+  explain-on-first-use: {}
+  internal-only:
+    family: 작업 담당 방식
+    fan-out: 여러 담당자가 나눠 검토
+    collapse: 한 담당자가 맡아 처리
+    concrete worker: 실제 변경 담당자
+    verification family: 검증 담당 역할
+    route-to: 재작업 시작 상태
+must-include:
+  - 한 문장 가치 제안과 대상 독자
+  - 설치 전제조건과 복사 가능한 첫 테스트 경로
+  - 네 가지 모드의 독자 작업 기준 선택법
+  - 저장소 분석부터 패치 적용까지의 한 화면 처리 흐름
+  - 사실, 명령, 경로, 비밀 값, 보호 영역, 품질 근거에 대한 안전장치
+  - 생성되는 주요 산출물과 명시적 적용 경계
+  - Codex 경로 구현 범위와 도구 간 동등성 한계
+  - 아키텍처, 시각화, 상태기계 상세 문서 링크
+must-exclude:
+  - 저장소 근거 없는 최상 품질, 성능, 생산 준비 완료 주장
+  - 전체 상태 이름과 내부 역할 배치를 첫 화면에서 장황하게 나열하는 설명
+  - 내부 오케스트레이션 영문 용어를 독자용 개념처럼 노출하는 문장
+  - 검증되지 않은 설치·실행 명령
+protected-sections: []
@@ -0,0 +1,363 @@
+schema-version: 1
+repository-snapshot-hash: sha256:8ea3e3693ce644a2576f9a8670088a36e5964ac8edaca5b279f7281e44aa428b
+project-name: readme-harness
+languages: [Python]
+frameworks: [jsonschema, PyYAML, pytest]
+facts:
+  - id: F-PROJECT-001
+    category: purpose
+    key: harness-description
+    value: 저장소 사실과 사용자 요구를 바탕으로 GitHub README를 분석·설계·작성·검증하는 하네스
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        line-start: 2
+        line-end: 13
+        source-kind: harness-configuration
+  - id: F-RUNTIME-001
+    category: prerequisite
+    key: python-version
+    value: Python >=3.12
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: pyproject.toml
+        line-start: 1
+        line-end: 5
+        source-kind: build-configuration
+  - id: F-DEPENDENCY-001
+    category: dependency
+    key: runtime-and-dev-dependencies
+    value: [jsonschema>=4.20, PyYAML>=6.0, pytest>=8.0]
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: pyproject.toml
+        line-start: 5
+        line-end: 8
+        source-kind: build-configuration
+  - id: F-MODE-001
+    category: capability
+    key: implemented-modes
+    value: [bootstrap, audit, refresh, section-update]
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        line-start: 10
+        line-end: 13
+        source-kind: harness-configuration
+  - id: F-TOOL-001
+    category: compatibility
+    key: tool-boundary
+    value:
+      supported-tools: [codex, antigravity, claude]
+      deterministic-codex-drivers: implemented
+      cross-tool-equivalence: phase-4
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        line-start: 8
+        line-end: 13
+        source-kind: harness-configuration
+      - path: harness.yaml
+        line-start: 99
+        line-end: 107
+        source-kind: capability-boundary
+  - id: F-STATE-001
+    category: workflow
+    key: bootstrap-gates
+    value:
+      states: [INPUT_CAPTURED, REPOSITORY_SNAPSHOTTED, FACTS_EXTRACTED, PROJECT_PROFILED, README_PLANNED, README_DRAFTED, VISUALS_PLANNED, STRUCTURALLY_VALIDATED, TECHNICALLY_VERIFIED, QUALITY_REVIEWED]
+      final-preparation: READY_FOR_APPLY
+      final-apply: APPLIED
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/state.py
+        line-start: 71
+        line-end: 83
+        source-kind: state-machine-code
+  - id: F-VISUAL-001
+    category: visual-contract
+    key: included-visual-completeness
+    value: 개요 include 섹션, visual plan 섹션, README visual id, 요청 모드에 맞는 생성 소스 또는 자산을 함께 검사
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/visuals.py
+        line-start: 77
+        line-end: 183
+        source-kind: validator-code
+  - id: F-DRIVER-001
+    category: workflow
+    key: bootstrap-driver-boundary
+    value:
+      init-run: runs/<repo-id>/<run-id>에 state.json과 run-manifest.json을 생성
+      bootstrap-driver: 준비된 authoring artifacts를 QUALITY_REVIEWED까지 검증하며 후보나 대상 README를 작성하지 않음
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/scripts/init_run.py
+        line-start: 10
+        line-end: 37
+        source-kind: driver-code
+      - path: .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py
+        line-start: 1
+        line-end: 7
+        source-kind: driver-code
+  - id: F-AUTHORING-001
+    category: usage
+    key: model-authoring-boundary
+    value: 독립형 종단 간 생성 CLI가 아니라 도구가 requirement-driven-readme 스킬을 로드하고 모델 역할이 작성 산출물을 준비한 뒤 결정론 드라이버가 검증하는 구조
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: AGENTS.md
+        line-start: 1
+        line-end: 14
+        source-kind: codex-entrypoint
+      - path: harness.yaml
+        line-start: 100
+        line-end: 109
+        source-kind: capability-boundary
+  - id: F-TERM-001
+    category: prose-contract
+    key: public-terminology
+    value: 인라인 코드 식별자를 repository-facts.yaml과 대조하고 내부 전용 용어 노출과 첫 사용 설명을 검사
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/prose.py
+        line-start: 120
+        line-end: 207
+        source-kind: validator-code
+      - path: src/readme_harness/prose.py
+        line-start: 286
+        line-end: 379
+        source-kind: validator-code
+  - id: F-CLASSIFY-001
+    category: classification
+    key: root-first-python-classification
+    value: 루트 선언을 우선하고 테스트·픽스처·예제·샘플·vendor를 주 분류 신호에서 제외하며 pyproject.toml을 CLI·서비스·라이브러리로 구분
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/scan.py
+        line-start: 14
+        line-end: 103
+        source-kind: scanner-code
+      - path: src/readme_harness/classify.py
+        line-start: 6
+        line-end: 29
+        source-kind: classifier-code
+  - id: F-REVIEW-001
+    category: quality-contract
+    key: hash-bound-review-evidence
+    value: 품질 근거의 artifact, section-id, line-start, line-end, content-hash를 실제 README와 대조하고 review.md를 YAML에서 렌더링
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/review.py
+        line-start: 18
+        line-end: 103
+        source-kind: review-validator-code
+  - id: F-AUDIT-001
+    category: audit-contract
+    key: validated-atomic-audit-completion
+    value: audit findings를 스키마 검증하고 산출물을 원자적으로 기록한 뒤 AUDIT_COMPLETED로 전이
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/scripts/run_audit.py
+        line-start: 107
+        line-end: 134
+        source-kind: audit-driver-code
+  - id: F-APPLY-001
+    category: safety
+    key: explicit-apply-boundary
+    value:
+      prepared-artifacts: [README.generated.md, README.patch, apply-manifest.yaml]
+      checks: [reviewed-artifact-hashes, repository-freshness, generated-hash, target-before-hash, path-containment]
+      target-write: explicit apply_patch.py only
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        line-start: 134
+        line-end: 141
+        source-kind: apply-policy
+      - path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
+        line-start: 22
+        line-end: 67
+        source-kind: apply-driver-code
+  - id: F-MERGE-001
+    category: safety
+    key: refresh-preservation
+    value: refresh는 protected와 unmarked 영역을 보존하고 서로 다른 managed 편집을 manual-required 충돌로 기록
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/merge.py
+        line-start: 7
+        line-end: 79
+        source-kind: merge-code
+  - id: F-LAYOUT-001
+    category: structure
+    key: primary-paths
+    value: [.agents, src/readme_harness, tests, docs/architecture.md, docs/visuals.md, docs/state-machine.md, runs]
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        line-start: 125
+        line-end: 132
+        source-kind: harness-configuration
+      - path: docs/architecture.md
+        line-start: 1
+        line-end: 1
+        source-kind: documentation
+      - path: docs/visuals.md
+        line-start: 1
+        line-end: 1
+        source-kind: documentation
+      - path: docs/state-machine.md
+        line-start: 1
+        line-end: 1
+        source-kind: documentation
+  - id: F-ARTIFACT-001
+    category: artifact-contract
+    key: primary-authoring-artifacts
+    value: [README.md, readme-request.yaml, repository-facts.yaml, readme-brief.yaml, readme-outline.yaml, README.candidate.md, claim-map.yaml, visual-plan.yaml, prose-report.json, verification.json, review-findings.yaml, review.md, quality-manifest.yaml, audit-findings.yaml, audit-report.md, README.generated.md, README.patch, apply-manifest.yaml, runs/demo/first, runs/<repo-id>/<run-id>, requirement-driven-readme, bootstrap]
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py
+        line-start: 46
+        line-end: 56
+        source-kind: bootstrap-driver-code
+      - path: harness.yaml
+        line-start: 134
+        line-end: 141
+        source-kind: apply-policy
+  - id: F-SELF-README-001
+    category: readme-contract
+    key: own-readme-quality-tests
+    value: [library profile quality audit, 30-second reader order, python3 -m pytest -q, Mermaid, harness-flow]
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: tests/unit/test_own_readme_quality.py
+        line-start: 14
+        line-end: 38
+        source-kind: repository-owned-readme-test
+  - id: F-CI-001
+    category: testing
+    key: continuous-integration
+    value: GitHub Actions는 Python 3.12에서 개발 의존성을 설치하고 python -m pytest -q를 실행
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: .github/workflows/ci.yml
+        line-start: 1
+        line-end: 17
+        source-kind: ci-workflow
+  - id: F-USAGE-001
+    category: observability
+    key: adapter-supplied-model-usage
+    value: 어댑터가 제공한 단계별 입력·캐시 입력·출력 토큰과 컨텍스트 파일 기여를 run-manifest.json에 누적하며 미제공 값은 추정하지 않음
+    assertion-type: observed
+    confidence: high
+    evidence:
+      - path: src/readme_harness/usage.py
+        line-start: 11
+        line-end: 66
+        source-kind: usage-recorder-code
+      - path: docs/usage-metrics.md
+        line-start: 1
+        line-end: 29
+        source-kind: usage-documentation
+  - id: F-BENCH-001
+    category: limitation
+    key: quality-superiority-gate
+    value:
+      repository-types: 8
+      arms: [human-maintained, single-prompt, harness]
+      current-status: not-run
+      required-status: PASS
+      superiority-claims: prohibited-until-benchmark-pass
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: benchmarks/quality-benchmark.yaml
+        line-start: 1
+        line-end: 37
+        source-kind: benchmark-contract
+      - path: harness.yaml
+        line-start: 108
+        line-end: 114
+        source-kind: capability-boundary
+  - id: F-LIMIT-001
+    category: limitation
+    key: candidate-generation-boundary
+    value: 후보 작성은 LLM pipeline이며 결정론 코어가 아니고 도구 간 런타임 동등성은 phase-4 목표
+    assertion-type: declared
+    confidence: high
+    evidence:
+      - path: harness.yaml
+        line-start: 99
+        line-end: 107
+        source-kind: capability-boundary
+commands:
+  - id: CMD-001
+    command: python3 -m pip install -e ".[dev]"
+    cwd: .
+    source:
+      path: pyproject.toml
+    verification:
+      status: discovered
+      method: pyproject dependencies and editable install syntax
+  - id: CMD-002
+    command: python3 -m pytest -q
+    cwd: .
+    source:
+      path: pyproject.toml
+    verification:
+      status: executed
+      method: pytest execution in current workspace
+      level: execution
+      limitations: [운영체제와 새 가상환경에서의 설치까지 증명하지는 않음]
+  - id: CMD-003
+    command: python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
+    cwd: .
+    source:
+      path: .agents/skills/requirement-driven-readme/scripts/init_run.py
+    verification:
+      status: static-verified
+      method: python script path exists
+  - id: CMD-004
+    command: python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
+    cwd: .
+    source:
+      path: .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py
+    verification:
+      status: static-verified
+      method: python script path exists
+  - id: CMD-005
+    command: python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
+    cwd: .
+    source:
+      path: .agents/skills/requirement-driven-readme/scripts/generate_patch.py
+    verification:
+      status: static-verified
+      method: python script path exists
+  - id: CMD-006
+    command: python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
+    cwd: .
+    source:
+      path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
+    verification:
+      status: static-verified
+      method: python script path exists
@@ -0,0 +1,7 @@
+{
+  "git-sha": "636617ccd9f20440f21339f808557c096b55fec2",
+  "dirty": true,
+  "diff-hash": "sha256:8ea3e3693ce644a2576f9a8670088a36e5964ac8edaca5b279f7281e44aa428b",
+  "scanned-at": null,
+  "file-count": 228
+}
@@ -0,0 +1,144 @@
+schema-version: 1
+verdict: PASS
+score: 90
+scores:
+  project-specificity:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: overview
+        line-start: 12
+        line-end: 26
+        content-hash: sha256:e6881327a3a749eecb74b02636fbc9c3d254ce9b952896f59c7093d0d89e2799
+        observation: 주 독자를 README 작성·갱신 개발자로 명시하고 네 모드와 근거·적용 경계, 런타임 동등성 한계를 프로젝트 고유 특성으로 설명한다.
+  reader-journey:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: overview
+        line-start: 12
+        line-end: 26
+        content-hash: sha256:e6881327a3a749eecb74b02636fbc9c3d254ce9b952896f59c7093d0d89e2799
+        observation: 대상 독자, 제공 결과, 핵심 안전 경계와 구현 한계가 첫 개요에 모여 있어 후속 과업을 빠르게 판단할 수 있다.
+      - artifact: README.candidate.md
+        section-id: usage
+        line-start: 84
+        line-end: 95
+        content-hash: sha256:1cb56273e71777d93e55ce3eee23094d33f4d6d66b8e56d5f57b842107c8857a
+        observation: 네 모드를 새 작성, 감사, 보존 갱신, 부분 갱신이라는 독자 작업과 결과 기준으로 바로 선택할 수 있다.
+  technical-explanation:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: architecture
+        line-start: 135
+        line-end: 166
+        content-hash: sha256:f39304dc61c0a017a37676b2077d572aaf9c8bd78b24ae51eb125762d41ef623
+        observation: 사용자 요구와 저장소 근거가 계획, 작성, 시각 자료, 결정론적 검사, 독립 심사와 재작업으로 이어지는 책임과 흐름을 설명한다.
+      - artifact: README.candidate.md
+        section-id: safeguards
+        line-start: 168
+        line-end: 186
+        content-hash: sha256:f4aeba8e1e5aae86600fc4f2c70f10da1b67120222cf8c45912b88e9882fc509
+        observation: 용어·시각 자료·품질 근거·갱신 보호에 해당하는 검증 책임과 차단 조건을 구체적인 계약으로 구분한다.
+  task-usability:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: installation
+        line-start: 28
+        line-end: 42
+        content-hash: sha256:0854377cd971afc6408b317ba1308f319f8a2025bef86dfac262ab253e999565
+        observation: 전제조건, 복사 가능한 설치 명령과 새 가상환경에서의 미검증 범위를 함께 밝혀 설치 판단이 가능하다.
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 44
+        line-end: 82
+        content-hash: sha256:ee017689603496487003245c0cb4e00a7be4ac3a0eec8921a5edb111da68d78b
+        observation: 테스트 성공 기준, 모델 기반 작성 경계, 준비 산출물과 초기화·검증 명령을 순서대로 제시한다.
+      - artifact: README.candidate.md
+        section-id: api
+        line-start: 97
+        line-end: 133
+        content-hash: sha256:86cc70fd60e94877c1de9c3db099c67df7b18adedfebff01dc84217329d11fa0
+        observation: 입력, 주요 산출물, 패치 준비와 명시적 적용 명령을 분리해 검토 후 작업을 안전하게 수행할 수 있다.
+  prose-clarity:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: installation
+        line-start: 28
+        line-end: 42
+        content-hash: sha256:0854377cd971afc6408b317ba1308f319f8a2025bef86dfac262ab253e999565
+        observation: 런타임과 패키지 식별자를 인라인 코드로 구별하고 전제조건과 검증 한계를 직접적인 한국어로 설명한다.
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 44
+        line-end: 82
+        content-hash: sha256:ee017689603496487003245c0cb4e00a7be4ac3a0eec8921a5edb111da68d78b
+        observation: 독립 실행 도구가 아니라는 제한과 독자가 요청할 행동을 먼저 밝히며 기술 식별자는 인라인 코드로 구별한다.
+      - artifact: README.candidate.md
+        section-id: safeguards
+        line-start: 168
+        line-end: 186
+        content-hash: sha256:f4aeba8e1e5aae86600fc4f2c70f10da1b67120222cf8c45912b88e9882fc509
+        observation: 반복 종결 경고는 있으나 항목 구조와 구체적인 현재형 동사가 함께 쓰여 이해를 방해하지 않는다.
+  visual-judgment:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: architecture
+        line-start: 135
+        line-end: 166
+        content-hash: sha256:f39304dc61c0a017a37676b2077d572aaf9c8bd78b24ae51eb125762d41ef623
+        observation: 단일 Mermaid 흐름도가 두 입력의 결합, 작성과 그림의 합류, 독립 심사, 재작업과 명시적 적용을 한 화면에 보여 준다.
+hard-gates:
+  passed: true
+  failures: []
+reader-simulations:
+  30-seconds:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: overview
+        line-start: 12
+        line-end: 26
+        content-hash: sha256:e6881327a3a749eecb74b02636fbc9c3d254ce9b952896f59c7093d0d89e2799
+        observation: 도구의 정체성, 안전 목적과 README를 작성·갱신하는 개발자라는 대상을 모두 확인할 수 있다.
+  5-minutes:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 44
+        line-end: 82
+        content-hash: sha256:ee017689603496487003245c0cb4e00a7be4ac3a0eec8921a5edb111da68d78b
+        observation: 테스트 성공 기준, 모델 기반 작성 요청, 준비 산출물, 초기화와 결정론적 게이트 재생 순서를 확인할 수 있다.
+      - artifact: README.candidate.md
+        section-id: architecture
+        line-start: 135
+        line-end: 166
+        content-hash: sha256:f39304dc61c0a017a37676b2077d572aaf9c8bd78b24ae51eb125762d41ef623
+        observation: 요구와 근거가 작성·검사·독립 심사·재작업·적용으로 이어지는 전체 구조를 한 화면에서 식별할 수 있다.
+      - artifact: README.candidate.md
+        section-id: limitations
+        line-start: 214
+        line-end: 224
+        content-hash: sha256:10ae2331d6b1858e08b4affefc718b064393da0947295bf78246e4f6eb6c2038
+        observation: 모델 작성 의존성, 도구 간 동등성 미검증, 정적 명령 검증과 미실행 품질 벤치마크를 현재 한계로 구분한다.
+  contributor:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: tests
+        line-start: 188
+        line-end: 199
+        content-hash: sha256:7eb8e5a521f7d6a821377078e40f288a27fd197437a9bd25922013f5a11bc927
+        observation: 전체 테스트 명령, CI 환경과 자체 README 계약 범위를 기여 전에 확인할 수 있다.
+      - artifact: README.candidate.md
+        section-id: documentation
+        line-start: 201
+        line-end: 212
+        content-hash: sha256:97129977e42c81be1ff70cdfa2402147fed9366468c0e39dc48ba71b1c0259b2
+        observation: 구현·규칙·테스트 위치를 구분하고 아키텍처·상태기계·계측·벤치마크 상세 문서로 이동할 수 있다.
+findings: []
@@ -0,0 +1,22 @@
+# README quality review
+
+Verdict: **PASS** — 90/100
+
+## Dimension scores
+
+- project-specificity: 5/5
+- reader-journey: 5/5
+- technical-explanation: 4/5
+- task-usability: 4/5
+- prose-clarity: 4/5
+- visual-judgment: 5/5
+
+## Reader simulations
+
+- 30-seconds: PASS
+- 5-minutes: PASS
+- contributor: PASS
+
+## Findings
+
+No findings.
@@ -0,0 +1,12 @@
+{
+  "schema-version": 1,
+  "run-id": "20260720-review-remediation",
+  "repo-id": "readme-harness",
+  "mode": "bootstrap",
+  "target-repository": "/home/donghyeon/workspace/ai-tool/readme-harness",
+  "harness-version": "0.1.0",
+  "started-at": null,
+  "tool-adapter": "codex",
+  "input-hashes": {},
+  "usage": {}
+}
@@ -0,0 +1,347 @@
+{
+  "schema-version": 1,
+  "mode": "bootstrap",
+  "current": "APPLIED",
+  "history": [
+    {
+      "state": "INITIALIZED"
+    },
+    {
+      "state": "INPUT_CAPTURED",
+      "gates": [
+        {
+          "name": "request",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        }
+      ]
+    },
+    {
+      "state": "REPOSITORY_SNAPSHOTTED",
+      "gates": [
+        {
+          "name": "snapshot",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "diff-hash": "sha256:8ea3e3693ce644a2576f9a8670088a36e5964ac8edaca5b279f7281e44aa428b"
+          }
+        }
+      ]
+    },
+    {
+      "state": "FACTS_EXTRACTED",
+      "gates": [
+        {
+          "name": "facts",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "fact_ids": [
+              "F-PROJECT-001",
+              "F-RUNTIME-001",
+              "F-DEPENDENCY-001",
+              "F-MODE-001",
+              "F-TOOL-001",
+              "F-STATE-001",
+              "F-VISUAL-001",
+              "F-DRIVER-001",
+              "F-AUTHORING-001",
+              "F-TERM-001",
+              "F-CLASSIFY-001",
+              "F-REVIEW-001",
+              "F-AUDIT-001",
+              "F-APPLY-001",
+              "F-MERGE-001",
+              "F-LAYOUT-001",
+              "F-ARTIFACT-001",
+              "F-SELF-README-001",
+              "F-CI-001",
+              "F-USAGE-001",
+              "F-BENCH-001",
+              "F-LIMIT-001"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "PROJECT_PROFILED",
+      "gates": [
+        {
+          "name": "profile",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "profile": "library"
+          }
+        }
+      ]
+    },
+    {
+      "state": "README_PLANNED",
+      "gates": [
+        {
+          "name": "brief",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        },
+        {
+          "name": "outline",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "section_ids": [
+              "overview",
+              "installation",
+              "quick-start",
+              "usage",
+              "api",
+              "architecture",
+              "safeguards",
+              "tests",
+              "documentation",
+              "limitations"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "README_DRAFTED",
+      "gates": [
+        {
+          "name": "conformance",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "sections": [
+              "overview",
+              "installation",
+              "quick-start",
+              "usage",
+              "api",
+              "architecture",
+              "safeguards",
+              "tests",
+              "documentation",
+              "limitations"
+            ]
+          }
+        },
+        {
+          "name": "claim_map",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "claims": [
+              "C-PROJECT-001",
+              "C-MODE-001",
+              "C-SAFETY-SUMMARY-001",
+              "C-LIMIT-001",
+              "C-RUNTIME-001",
+              "C-INSTALL-001",
+              "C-TEST-COMMAND-001",
+              "C-AUTHORING-001",
+              "C-INIT-001",
+              "C-BOOTSTRAP-001",
+              "C-USAGE-001",
+              "C-INPUT-001",
+              "C-USAGE-METRICS-001",
+              "C-PREPARE-001",
+              "C-APPLY-001",
+              "C-FLOW-001",
+              "C-TERM-001",
+              "C-VISUAL-001",
+              "C-REVIEW-001",
+              "C-AUDIT-001",
+              "C-MERGE-001",
+              "C-APPLY-SAFETY-001",
+              "C-CI-001",
+              "C-LAYOUT-001",
+              "C-LIMIT-002",
+              "C-VERIFY-LIMIT-001",
+              "C-BENCH-LIMIT-001"
+            ],
+            "derived-statements": {
+              "C-PROJECT-001": "이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,\n명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.",
+              "C-MODE-001": "`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다.",
+              "C-SAFETY-SUMMARY-001": "저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을\n넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인\n근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.",
+              "C-LIMIT-001": "결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며,\n다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.",
+              "C-RUNTIME-001": "`Python` 3.12 이상이 필요합니다.\n런타임 의존성은 `jsonschema`와 `PyYAML`입니다.\n개발 의존성은 `pytest`입니다.",
+              "C-INSTALL-001": "이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지\n실행해 증명하지 않았습니다.",
+              "C-TEST-COMMAND-001": "자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새\n가상환경의 동일한 결과까지 보장하는 계약은 아닙니다.",
+              "C-AUTHORING-001": "이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서\n`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성\n역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사\n산출물을 준비합니다.",
+              "C-INIT-001": "이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.",
+              "C-BOOTSTRAP-001": "드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 `QUALITY_REVIEWED`까지\n검증합니다.",
+              "C-USAGE-001": "네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어\n있습니다.",
+              "C-INPUT-001": "`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을\n정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은\n`runs/<repo-id>/<run-id>` 아래에서 격리합니다.",
+              "C-USAGE-METRICS-001": "어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지\n않은 값은 0으로 추정하지 않습니다.",
+              "C-PREPARE-001": "이 단계는 `README.generated.md`, `README.patch`, `apply-manifest.yaml`을 만들고\n상태를 `READY_FOR_APPLY`로 전진시킵니다.",
+              "C-APPLY-001": "적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.",
+              "C-FLOW-001": "사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는\n근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적\n게이트와 독립 품질 심사를 통과해야 패치가 됩니다.",
+              "C-TERM-001": "- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.\n- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을\n  차단합니다.",
+              "C-VISUAL-001": "- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.\n- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을\n  차단합니다. <!-- claim-id: C-TERM-001 -->\n- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이\n  일치해야 시각 자료 게이트를 통과합니다.",
+              "C-REVIEW-001": "- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.\n- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을\n  차단합니다. <!-- claim-id: C-TERM-001 -->\n- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이\n  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->\n- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,\n  `review.md`는 검증된 YAML에서 렌더링합니다.",
+              "C-AUDIT-001": "- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.\n- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을\n  차단합니다. <!-- claim-id: C-TERM-001 -->\n- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이\n  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->\n- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,\n  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->\n- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로\n  전진합니다.",
+              "C-MERGE-001": "- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.\n- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을\n  차단합니다. <!-- claim-id: C-TERM-001 -->\n- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이\n  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->\n- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,\n  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->\n- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로\n  전진합니다. <!-- claim-id: C-AUDIT-001 -->\n- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새\n  후보가 충돌하면 자동 적용을 막습니다.",
+              "C-APPLY-SAFETY-001": "- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.\n- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을\n  차단합니다. <!-- claim-id: C-TERM-001 -->\n- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이\n  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->\n- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,\n  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->\n- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로\n  전진합니다. <!-- claim-id: C-AUDIT-001 -->\n- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새\n  후보가 충돌하면 자동 적용을 막습니다. <!-- claim-id: C-MERGE-001 -->\n- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나\n  적용을 차단합니다.",
+              "C-CI-001": "GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은\nPython 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행\n경로, Mermaid 그림 결정을 확인합니다.",
+              "C-LAYOUT-001": "주요 구현은 `src/readme_harness`, 스키마·규칙·워크플로는 `.agents`, 테스트는\n`tests`에 있습니다.",
+              "C-LIMIT-002": "- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된\n  산출물을 검증하고 상태를 전진시킵니다.\n- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증\n  목표입니다.",
+              "C-VERIFY-LIMIT-001": "- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된\n  산출물을 검증하고 상태를 전진시킵니다.\n- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증\n  목표입니다. <!-- claim-id: C-LIMIT-002 -->\n- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은\n  명령은 실제 실행 성공을 뜻하지 않습니다.",
+              "C-BENCH-LIMIT-001": "- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된\n  산출물을 검증하고 상태를 전진시킵니다.\n- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증\n  목표입니다. <!-- claim-id: C-LIMIT-002 -->\n- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은\n  명령은 실제 실행 성공을 뜻하지 않습니다. <!-- claim-id: C-VERIFY-LIMIT-001 -->\n- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다.\n  `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다."
+            }
+          }
+        }
+      ]
+    },
+    {
+      "state": "VISUALS_PLANNED",
+      "gates": [
+        {
+          "name": "visual_plan",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "visuals": [
+              "harness-flow"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "STRUCTURALLY_VALIDATED",
+      "gates": [
+        {
+          "name": "github_markdown",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        },
+        {
+          "name": "reader_prose",
+          "ok": true,
+          "warnings": [
+            "KO-REPEATED-ENDING line 4: 같은 문장 종결이 이어져 설명이 기계적으로 들릴 수 있습니다."
+          ],
+          "data": {
+            "schema-version": 1,
+            "policy-id": "korean-reader-prose-v1",
+            "language": "ko-KR",
+            "applicable": true,
+            "scope": "candidate",
+            "state": "PASS_WITH_WARNINGS",
+            "summary": {
+              "errors": 0,
+              "warnings": 1,
+              "sentences": 108,
+              "prose-characters": 2081,
+              "hangul-characters": 1839
+            },
+            "findings": [
+              {
+                "rule-id": "KO-REPEATED-ENDING",
+                "severity": "warning",
+                "line": 4,
+                "section": "README Harness",
+                "region-kind": "candidate",
+                "excerpt": "합니다 (29/43문장)",
+                "message": "같은 문장 종결이 이어져 설명이 기계적으로 들릴 수 있습니다.",
+                "suggestion": "정의, 절차, 제한에 맞춰 현재형 동사와 명사형 표제를 섞어 쓰세요.",
+                "source-ids": [
+                  "NIKL-EASY-PUBLIC-LANGUAGE"
+                ],
+                "id": "P-001"
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "state": "TECHNICALLY_VERIFIED",
+      "gates": [
+        {
+          "name": "verify",
+          "ok": true,
+          "warnings": [
+            "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+            "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+          ],
+          "data": {
+            "schema-version": 1,
+            "state": "PASS_WITH_MANUAL",
+            "verification-level": "static",
+            "execution-verified": false,
+            "checks": {
+              "commands": {
+                "total": 6,
+                "verified": 4,
+                "manual-required": 2,
+                "failed": 0
+              },
+              "paths": {
+                "total": 9,
+                "verified": 9,
+                "failed": 0
+              },
+              "anchors": {
+                "total": 0,
+                "verified": 0,
+                "failed": 0
+              },
+              "readme-contracts": {
+                "total": 0,
+                "verified": 0,
+                "failed": 0
+              }
+            },
+            "failures": [],
+            "limitations": [
+              "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+              "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+            ]
+          }
+        },
+        {
+          "name": "secret_scan",
+          "ok": true,
+          "warnings": [],
+          "data": null
+        }
+      ]
+    },
+    {
+      "state": "QUALITY_REVIEWED",
+      "gates": [
+        {
+          "name": "review",
+          "ok": true,
+          "warnings": [],
+          "data": {
+            "verdict": "PASS",
+            "score": 90,
+            "findings": [],
+            "report-valid": true
+          }
+        }
+      ]
+    },
+    {
+      "state": "READY_FOR_APPLY",
+      "gates": []
+    },
+    {
+      "state": "APPLIED",
+      "gates": []
+    }
+  ],
+  "rework": {
+    "iterations": 0,
+    "findings": {}
+  }
+}
@@ -0,0 +1,34 @@
+{
+  "schema-version": 1,
+  "state": "PASS_WITH_MANUAL",
+  "verification-level": "static",
+  "execution-verified": false,
+  "checks": {
+    "commands": {
+      "total": 6,
+      "verified": 4,
+      "manual-required": 2,
+      "failed": 0
+    },
+    "paths": {
+      "total": 9,
+      "verified": 9,
+      "failed": 0
+    },
+    "anchors": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    },
+    "readme-contracts": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    }
+  },
+  "failures": [],
+  "limitations": [
+    "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+    "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+  ]
+}
@@ -0,0 +1,40 @@
+schema-version: 1
+visuals:
+  - id: harness-flow
+    section: architecture
+    type: request-flow
+    purpose: 저장소 분석과 사용자 요구가 후보 작성, 그림 생성, 결정론적 게이트, 독립 품질 심사를 거쳐 패치와 명시적 적용으로 이어지는 흐름을 보여준다.
+    placeholder-text: 왼쪽의 두 입력이 계획에서 합쳐지고 작성과 그림이 검증으로 모인 뒤 품질 심사에서 재작업 또는 적용으로 갈라지는 Mermaid 흐름도다.
+    must-show:
+      - 사용자 요구와 대상 저장소라는 두 입력
+      - 독자 흐름·용어·그림 결정과 저장소 근거·프로젝트 분류
+      - README 작성과 그림 소스·자산 생성
+      - 근거·명령·경로·문체 검사와 독립 품질 심사
+      - 수정 필요 시 계획으로 돌아가는 재작업
+      - 통과 후 패치 준비와 명시적 적용
+      - 해시 기반 실행 산출물
+    relationships:
+      - 사용자 요구 -> 독자 흐름·용어·그림 결정
+      - 대상 저장소 -> 근거 수집·프로젝트 분류
+      - 근거 수집·프로젝트 분류 -> 독자 흐름·용어·그림 결정
+      - 계획 -> README 작성
+      - 계획 -> 그림 소스·자산 생성
+      - README 작성 + 그림 -> 결정론적 검사
+      - 결정론적 검사 -> 독립 품질 심사
+      - 독립 품질 심사 -> 계획 (수정 필요)
+      - 독립 품질 심사 -> 패치 준비·명시적 적용 (통과)
+    emphasize:
+      - 의미 판단과 결정론적 검증의 경계를 별도 노드로 나눈다.
+      - 재작업 화살표와 정방향 적용 흐름을 다른 라벨로 구분한다.
+      - 해시 기반 산출물이 분석·계획·검증·적용에 연결됨을 보인다.
+    avoid:
+      - 전체 내부 상태 이름을 노드에 나열하지 않는다.
+      - Claude와 Antigravity 런타임 동등성을 구현 완료처럼 표현하지 않는다.
+      - 자동 적용처럼 보이는 우회 경로를 만들지 않는다.
+    placement:
+      after-section-id: architecture
+    accessibility:
+      alt-text: 사용자 요구와 대상 저장소에서 출발해 계획, README와 그림 작성, 결정론적 검사, 독립 품질 심사를 거친다. 수정이 필요하면 계획으로 돌아가고 통과하면 패치를 준비한 뒤 별도로 적용한다.
+    production:
+      format: mermaid
+      status: embedded