readme-haness/runs/readme-harness/20260720-review-remediation/README.patch

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