--- 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 +이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고, +명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다. + +- 새 README 작성 +- 기존 문서 점검 +- 사람 작성 영역을 보존한 갱신 +- 특정 섹션과 관련 검증 산출물의 재생성 +- 검토 후 별도로 실행하는 적용 + + +## 무엇을 만드는가 + +README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다. + +`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다. + +저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을 +넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인 +근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다. + + +결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며, +다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다. + + + +## 설치 + +`Python` 3.12 이상이 필요합니다. +런타임 의존성은 `jsonschema`와 `PyYAML`입니다. +개발 의존성은 `pytest`입니다. + +저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다. + +```bash +python3 -m pip install -e ".[dev]" +``` + +이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지 +실행해 증명하지 않았습니다. + + +## 빠른 시작 + +먼저 전체 테스트를 실행합니다. + +```bash +python3 -m pytest -q +``` + +종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재 +README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다. + +자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새 +가상환경의 동일한 결과까지 보장하는 계약은 아닙니다. + +이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서 +`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성 +역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사 +산출물을 준비합니다. + +대상 저장소용 실행 디렉터리를 만듭니다. + +```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`에 상태와 실행 매니페스트를 초기화합니다. + + +실행 디렉터리에 `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`까지 +검증합니다. + + +## 사용 모드 + +| 작업 | 모드 | 결과 | +|---|---|---| +| README가 없거나 전면 재작성 | `bootstrap` | 검증된 후보와 적용 준비용 패치 | +| 기존 문서의 결함만 점검 | `audit` | 감사 결과와 검증 보고서, 후보·패치 없음 | +| 사람 작성 영역을 보존한 갱신 | `refresh` | 3방향 병합과 병합본 전체 재검증 | +| 한 섹션과 파급 산출물 갱신 | `section-update` | 관련 산출물 무효화 후 갱신 검증 재실행 | + +네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어 +있습니다. + + +## 요청 API, 설정과 산출물 + +`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을 +정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은 +`runs//` 아래에서 격리합니다. + +어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지 +않은 값은 0으로 추정하지 않습니다. + +대표 산출물은 다음 순서로 이어집니다. ```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/// 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 /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`로 전진시킵니다. + +검토가 끝난 패치만 별도 명령으로 적용합니다. + +```bash +python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository +``` + +적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다. + + + +## 동작 방식 + +사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는 +근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적 +게이트와 독립 품질 심사를 통과해야 패치가 됩니다. + +```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 +``` + + + +구성요소 책임과 컨텍스트 경계는 [아키텍처 문서](docs/architecture.md)에, +모드별 전이는 [상태기계 문서](docs/state-machine.md)에 정리했습니다. + + +## 안전장치 + +- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다. +- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을 + 차단합니다. +- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이 + 일치해야 시각 자료 게이트를 통과합니다. +- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고, + `review.md`는 검증된 YAML에서 렌더링합니다. +- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로 + 전진합니다. +- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새 + 후보가 충돌하면 자동 적용을 막습니다. +- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나 + 적용을 차단합니다. + +시각 자료의 소스·자산·대체 텍스트·신선도 규칙은 +[시각 자료 정책](docs/visuals.md)에서 확인할 수 있습니다. + + +## 테스트 + +전체 회귀 테스트는 다음 명령으로 실행합니다. ```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 그림 결정을 확인합니다. + + +## 상세 문서 + +- [구성요소와 컨텍스트 경계](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`에 있습니다. + + +## 현재 한계 + +- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된 + 산출물을 검증하고 상태를 전진시킵니다. +- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증 + 목표입니다. +- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은 + 명령은 실제 실행 성공을 뜻하지 않습니다. +- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다. + `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다.