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