donghyeon.kang/readme-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

init: readme 작성 하네스 설계

Browse Source
This commit is contained in:
DongHyeonka
2026-07-24 13:26:18 +09:00
parent 7fb4217f7c
commit c708cbcf9a
317 changed files with 24223 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
runs/readme-harness/20260720-review-remediation/README.candidate.md
+224
View File
@@ -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 -->
runs/readme-harness/20260720-review-remediation/README.generated.md
+224
View File
@@ -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 -->
runs/readme-harness/20260720-review-remediation/README.patch
+295
View File
@@ -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 -->
runs/readme-harness/20260720-review-remediation/apply-manifest.yaml
+7
View File
@@ -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
runs/readme-harness/20260720-review-remediation/claim-map.yaml
+160
View File
@@ -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
runs/readme-harness/20260720-review-remediation/prose-report.json
+31
View File
@@ -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"
}
]
}
runs/readme-harness/20260720-review-remediation/quality-manifest.yaml
+14
View File
@@ -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
runs/readme-harness/20260720-review-remediation/readme-brief.yaml
+47
View File
@@ -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
runs/readme-harness/20260720-review-remediation/readme-outline.yaml
+129
View File
@@ -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 전 우월성 주장 금지
runs/readme-harness/20260720-review-remediation/readme-request.yaml
+57
View File
@@ -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: []
runs/readme-harness/20260720-review-remediation/repository-facts.yaml
+363
View File
@@ -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
runs/readme-harness/20260720-review-remediation/repository-snapshot.json
+7
View File
@@ -0,0 +1,7 @@
{
"git-sha": "636617ccd9f20440f21339f808557c096b55fec2",
"dirty": true,
"diff-hash": "sha256:8ea3e3693ce644a2576f9a8670088a36e5964ac8edaca5b279f7281e44aa428b",
"scanned-at": null,
"file-count": 228
}
runs/readme-harness/20260720-review-remediation/review-findings.yaml
+144
View File
@@ -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: []
runs/readme-harness/20260720-review-remediation/review.md
+22
View File
@@ -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.
runs/readme-harness/20260720-review-remediation/run-manifest.json
+12
View File
@@ -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": {}
}
runs/readme-harness/20260720-review-remediation/state.json
+347
View File
@@ -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": {}
}
}
runs/readme-harness/20260720-review-remediation/verification.json
+34
View File
@@ -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)"
]
}
runs/readme-harness/20260720-review-remediation/visual-plan.yaml
+40
View File
@@ -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