diff --git a/README.md b/README.md index 14c5b67..768f814 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # README Harness -README Harness는 Codex및 claude가 저장소에서 확인한 사실과 사용자가 지시한 목적을 기반으로 GitHub README를 만드는 검증 중심 Python 도구입니다. 명령, 경로, 링크, Markdown 구조와 비밀 값 노출을 검사하고 별도 품질 검토를 거친 패치를 제공하며, 사용자가 적용하기 전에는 원본 `README.md`를 바꾸지 않습니다. +README Harness는 GitHub README를 만드는 검증 중심 Python 도구입니다. Codex 및 claude가 저장소에서 확인한 사실과 사용자가 지시한 목적을 근거로 삼습니다. 명령, 경로, 링크, Markdown 구조와 비밀 값 노출을 검사하고 별도 품질 검토를 거친 패치를 제공합니다. 사용자가 적용하기 전에는 원본 `README.md`를 바꾸지 않습니다. -대상 저장소를 처음 문서화하거나 기존 README의 정확성과 읽기 흐름을 함께 점검하려는 개발자를 위한 도구입니다. 현재는 Codex와 claude만 지원합니다. +대상 저장소를 처음 문서화하려는 개발자를 위한 도구입니다. 기존 README의 정확성과 읽기 흐름을 함께 점검할 때도 씁니다. 현재는 Codex와 claude만 지원합니다. ## 빠른 시작 @@ -23,7 +23,7 @@ README Harness는 Codex및 claude가 저장소에서 확인한 사실과 사용 .venv/bin/readme-harness apply /work/acme-api ``` -적용 명령은 검토 이후 생성본, 검토 결과, 대상 README 또는 저장소가 바뀌었으면 중단됩니다. +검토 이후에 생성본, 검토 결과, 대상 README 또는 저장소가 바뀌었으면 적용 명령은 중단됩니다. ## 작업 선택 @@ -42,11 +42,11 @@ README Harness는 Codex및 claude가 저장소에서 확인한 사실과 사용 ## 생성 흐름 1. 작성자는 사용자 요구와 저장소를 읽고 일반 Markdown 초안과 근거가 있는 사실 목록을 만듭니다. -2. 하네스는 초안을 검사하고 `README.generated.md`와 `README.patch`를 준비합니다. 첫 검증 통과 결과는 `REVIEW_REQUIRED`이며 원본 README는 그대로 남습니다. +2. 하네스는 초안을 검사하고 `README.generated.md`와 `README.patch`를 준비합니다. 첫 검증을 통과하면 결과는 `REVIEW_REQUIRED`이며 원본 README는 그대로 남습니다. 3. 읽기 전용 검토자가 GitHub 방문자에게 보일 생성본을 평가합니다. `NEEDS_FIX`이면 작성자가 한 번만 수정하고 전체 검증과 검토를 다시 실행합니다. 4. 검토까지 통과한 실행은 `READY`가 됩니다. 이후 사용자가 `apply`를 실행해야 대상 README가 바뀝니다. -이 절차는 작성과 품질 판단을 Codex가 맡고, 반복 가능한 형식·경로·명령 검사를 코드가 맡도록 경계를 나눕니다. +이 절차는 작성과 품질 판단을 Codex가 맡고 반복 가능한 형식·경로·명령 검사를 코드가 맡도록 경계를 나눕니다. ## 결과 파일 @@ -60,7 +60,7 @@ README Harness는 Codex및 claude가 저장소에서 확인한 사실과 사용 | `facts.json` | 프로젝트 정보, 명령, 근거 파일 | | `review.json` | 생성본에 결합된 별도 품질 검토 결과 | -첫 생성 단계에는 앞의 네 파일만 존재합니다. 품질 검토를 실행한 뒤 `review.json`이 추가됩니다. 검증에 실패하면 이유는 `validation.json`에 남고 적용 가능한 패치는 제공되지 않습니다. +첫 생성 단계에는 앞의 네 파일만 존재합니다. 품질 검토를 실행한 뒤 `review.json`이 추가됩니다. 검증에 실패하면 이유는 `validation.json`에 남고 적용할 수 있는 패치는 제공되지 않습니다. ## 검사와 적용 보호 @@ -68,7 +68,7 @@ README Harness는 Codex및 claude가 저장소에서 확인한 사실과 사용 - 코드 블록 닫힘, 제목 단계와 중복 앵커, 이미지 대체 텍스트, 이식할 수 없는 로컬 링크를 검사합니다. - README에 적힌 명령을 프로젝트 메타데이터와 저장소 파일을 기준으로 정적으로 확인합니다. - README와 사실 파일에서 할당된 비밀 값, 자격 증명이 든 연결 문자열, 개인 키, AWS 액세스 키 형식을 검사합니다. -- 적용 직전에 생성본, 검토 파일, 대상 README와 저장소의 해시를 다시 비교합니다. +- 적용 직전에는 생성본, 검토 파일, 대상 README와 저장소의 해시를 다시 비교합니다. - 파일 교체는 임시 파일을 완성한 뒤 원자적으로 수행합니다. ## Python API @@ -86,7 +86,7 @@ result = build_readme( print(result.status) ``` -함수의 입력과 산출물 경계, 외부 사실 결합 방식은 [아키텍처 문서](docs/architecture.md)에 정리되어 있습니다. +함수의 입력과 산출물 경계, 외부 사실을 결합하는 방식은 [아키텍처 문서](docs/architecture.md)에 정리되어 있습니다. ## 개발 @@ -97,11 +97,11 @@ print(result.status) .venv/bin/python -m pytest -q ``` -테스트는 `tests/`에 있으며, GitHub Actions도 Python 3.12에서 같은 테스트 명령을 실행합니다. CLI 진입점은 `readme_harness.cli:main`, 공개 Python 진입점은 `readme_harness.build_readme(...)`입니다. +테스트는 `tests/`에 있으며 GitHub Actions도 Python 3.12에서 같은 테스트 명령을 실행합니다. CLI 진입점은 `readme_harness.cli:main`이고 공개 Python 진입점은 `readme_harness.build_readme(...)`입니다. ## 현재 한계 -- 문장과 정보 구조는 Codex및 claude가 작성합니다. CLI 자체는 저장소만 보고 새 README 문장을 생성하지 않습니다. -- 명령 검증은 프로젝트 선언과 파일을 이용한 정적 검사입니다. 외부 서비스, 자격 증명, 배포 환경에서의 실행 성공까지 보장하지 않습니다. +- 문장과 정보 구조는 Codex 및 claude가 작성합니다. CLI 자체는 저장소만 보고 새 README 문장을 생성하지 않습니다. +- 명령 검증은 프로젝트 선언과 파일을 이용한 정적 검사입니다. 외부 서비스, 자격 증명, 배포 환경에서 실행에 성공하는 것까지 보장하지 않습니다. - 생성 후보는 README 전체 문서입니다. 기존 문서의 일부 구역만 자동 병합하지 않으므로 적용 전에 전체 패치를 확인해야 합니다. -- 자동 수정 기회는 한 번입니다. 두 번째 품질 검토도 통과하지 못하면 남은 문제를 사용자에게 돌려줍니다. +- 자동으로 수정할 기회는 한 번입니다. 두 번째 품질 검토도 통과하지 못하면 남은 문제를 사용자에게 돌려줍니다. diff --git a/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.bin b/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.bin index 63e95ea..92858b3 100644 Binary files a/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.bin and b/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.bin differ diff --git a/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.lock b/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.lock index 2037ae9..140e1b4 100644 Binary files a/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.lock and b/tests/fixtures/existing-readme-backend/.gradle/9.2.0/fileHashes/fileHashes.lock differ diff --git a/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock b/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock index 0ed39e2..7e43122 100644 Binary files a/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock and b/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock differ diff --git a/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/cache.properties b/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/cache.properties index ca7a5dd..ade6918 100644 --- a/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/cache.properties +++ b/tests/fixtures/existing-readme-backend/.gradle/buildOutputCleanup/cache.properties @@ -1,2 +1,2 @@ -#Fri Jul 24 13:26:01 KST 2026 +#Tue Jul 28 19:06:24 KST 2026 gradle.version=8.9 diff --git a/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.bin b/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.bin index 63e95ea..92858b3 100644 Binary files a/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.bin and b/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.bin differ diff --git a/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.lock b/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.lock index 298a0de..e818329 100644 Binary files a/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.lock and b/tests/fixtures/valid-backend/.gradle/9.2.0/fileHashes/fileHashes.lock differ diff --git a/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock b/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock index 2e8330a..dcbefd9 100644 Binary files a/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock and b/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/buildOutputCleanup.lock differ diff --git a/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/cache.properties b/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/cache.properties index ca7a5dd..0f46051 100644 --- a/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/cache.properties +++ b/tests/fixtures/valid-backend/.gradle/buildOutputCleanup/cache.properties @@ -1,2 +1,2 @@ -#Fri Jul 24 13:26:01 KST 2026 +#Tue Jul 28 19:06:28 KST 2026 gradle.version=8.9 diff --git a/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.bin b/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.bin index 63e95ea..92858b3 100644 Binary files a/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.bin and b/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.bin differ diff --git a/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.lock b/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.lock index 4881750..8c8cd99 100644 Binary files a/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.lock and b/tests/quality/backend-service/.gradle/9.2.0/fileHashes/fileHashes.lock differ diff --git a/tests/quality/backend-service/.gradle/buildOutputCleanup/buildOutputCleanup.lock b/tests/quality/backend-service/.gradle/buildOutputCleanup/buildOutputCleanup.lock index 945f10a..06fa799 100644 Binary files a/tests/quality/backend-service/.gradle/buildOutputCleanup/buildOutputCleanup.lock and b/tests/quality/backend-service/.gradle/buildOutputCleanup/buildOutputCleanup.lock differ diff --git a/tests/quality/backend-service/.gradle/buildOutputCleanup/cache.properties b/tests/quality/backend-service/.gradle/buildOutputCleanup/cache.properties index e1b7cb4..f680f52 100644 --- a/tests/quality/backend-service/.gradle/buildOutputCleanup/cache.properties +++ b/tests/quality/backend-service/.gradle/buildOutputCleanup/cache.properties @@ -1,2 +1,2 @@ -#Fri Jul 24 13:26:00 KST 2026 -gradle.version=8.9 +#Tue Jul 28 19:06:18 KST 2026 +gradle.version=9.2.0