schema-version: 1
repository-snapshot-hash: sha256:2ff902bd9a7de01648f972d099614584bc26fa84c1492cec61dc6da82e4f6275
project-name: readme-harness
languages: [Python, Markdown, YAML]
frameworks: []
facts:
  - id: F-PROJECT-001
    category: project
    key: identity
    value:
      name: readme-harness
      version: 0.1.0
      purpose: 저장소 사실과 사용자 요구를 바탕으로 GitHub README를 분석·설계·작성·검증합니다.
    assertion-type: declared
    confidence: high
    evidence:
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 2
        line-end: 6
      - path: pyproject.toml
        source-kind: build-manifest
        line-start: 1
        line-end: 4
  - id: F-RUNTIME-001
    category: prerequisites
    key: python-and-development
    value:
      python-minimum: "3.12"
      runtime-packages: [jsonschema, PyYAML]
      development-tool: pytest
    assertion-type: declared
    confidence: high
    evidence:
      - path: pyproject.toml
        source-kind: build-manifest
        line-start: 1
        line-end: 13
  - id: F-TOOL-PROFILE-001
    category: audience
    key: tool-profile
    value:
      primary-outcome: reviewed-patch-created
      max-primary-steps: 4
      development-command-as-first-step: false
      representative-proof-required: true
    assertion-type: declared
    confidence: high
    evidence:
      - path: .agents/profiles/tool.yaml
        source-kind: profile
        line-start: 1
        line-end: 21
  - id: F-MODES-001
    category: capability
    key: implemented-modes
    value: [bootstrap, audit, refresh, section-update]
    assertion-type: declared
    confidence: high
    evidence:
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 10
        line-end: 13
  - id: F-WORKFLOW-001
    category: workflow
    key: public-flow
    value: 사용자 요구와 저장소 근거를 분리해 계획하고, 모델 작성 뒤 검사와 독립 검토를 거쳐 패치 준비와 명시적 적용으로 이어집니다.
    assertion-type: declared
    confidence: high
    evidence:
      - path: docs/architecture.md
        source-kind: documentation
        line-start: 3
        line-end: 49
      - path: .agents/skills/requirement-driven-readme/SKILL.md
        source-kind: skill-contract
        line-start: 27
        line-end: 45
  - id: F-AUDIT-001
    category: workflow
    key: audit-behavior
    value: audit는 기존 README를 점검하며 대체 README나 패치를 만들지 않습니다.
    assertion-type: declared
    confidence: high
    evidence:
      - path: docs/state-machine.md
        source-kind: documentation
        line-start: 19
        line-end: 23
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 53
        line-end: 55
  - id: F-REFRESH-001
    category: safeguard
    key: refresh-merge-policy
    value:
      protected: never-modify
      unmarked: preserve
      managed: regenerate-or-3way-merge
      conflict-result: block
      post-merge-validation: required
    assertion-type: declared
    confidence: high
    evidence:
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 82
        line-end: 100
      - path: docs/state-machine.md
        source-kind: documentation
        line-start: 25
        line-end: 29
  - id: F-SECTION-001
    category: workflow
    key: section-update-behavior
    value: section-update는 선택한 섹션의 의존 결과를 무효화한 뒤 전체 문서 검증과 명시적 적용 경계를 다시 거칩니다.
    assertion-type: declared
    confidence: high
    evidence:
      - path: docs/state-machine.md
        source-kind: documentation
        line-start: 31
        line-end: 36
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 116
        line-end: 122
  - id: F-VERIFY-001
    category: architecture
    key: editorial-and-verification-separation
    value: 모델 역할이 문장을 작성하고 Python 검사가 근거, 문장, 명령, 경로, 링크, 비밀 값, 그림, 해시와 적용 경계를 확인합니다.
    assertion-type: declared
    confidence: high
    evidence:
      - path: docs/architecture.md
        source-kind: documentation
        line-start: 3
        line-end: 6
      - path: docs/architecture.md
        source-kind: documentation
        line-start: 40
        line-end: 49
  - id: F-AUTHORITY-001
    category: trust
    key: evidence-authority
    value:
      technical-facts-source: repository-facts.yaml
      intent-source: readme-request.yaml
      repository-content-trust: untrusted-data
    assertion-type: declared
    confidence: high
    evidence:
      - path: .agents/skills/requirement-driven-readme/SKILL.md
        source-kind: skill-contract
        line-start: 27
        line-end: 29
      - path: docs/architecture.md
        source-kind: documentation
        line-start: 67
        line-end: 72
  - id: F-CLAIM-001
    category: safeguard
    key: factual-claim-traceability
    value: 사실 주장은 알려진 근거 ID를 참조해야 하며 한 claim-id 마커는 정확히 한 문장만 가리킵니다.
    assertion-type: observed
    confidence: high
    evidence:
      - path: src/readme_harness/claims.py
        source-kind: implementation
        symbol: validate_claim_map
        line-start: 45
        line-end: 100
  - id: F-PROSE-001
    category: safeguard
    key: reader-prose-validation
    value: 같은 문단의 연속 줄을 합친 뒤 문장 길이와 표현을 검사하며 목록과 표의 각 항목은 따로 검사합니다.
    assertion-type: observed
    confidence: high
    evidence:
      - path: src/readme_harness/prose.py
        source-kind: implementation
        symbol: _visible_lines
        line-start: 82
        line-end: 150
      - path: tests/unit/test_prose.py
        source-kind: test
        symbol: test_hard_wrapped_paragraph_is_joined_before_sentence_length_check
        line-start: 110
        line-end: 126
  - id: F-VISUAL-001
    category: visual
    key: representative-output-policy
    value: 실제 결과 증명은 저장소의 지속 경로와 검토된 출처, 파일 해시를 가져야 합니다.
    assertion-type: declared
    confidence: high
    evidence:
      - path: docs/visuals.md
        source-kind: documentation
        line-start: 3
        line-end: 27
      - path: .agents/profiles/tool.yaml
        source-kind: profile
        line-start: 15
        line-end: 21
  - id: F-OUTPUT-001
    category: safeguard
    key: patch-preparation
    value:
      target: README.md
      outputs: [README.generated.md, README.patch, apply-manifest.yaml]
      checks: [repository-freshness, reviewed-artifact-hashes, target-path-containment]
    assertion-type: observed
    confidence: high
    evidence:
      - path: .agents/skills/requirement-driven-readme/scripts/generate_patch.py
        source-kind: implementation
        symbol: main
        line-start: 25
        line-end: 89
  - id: F-APPLY-001
    category: safeguard
    key: explicit-apply
    value:
      command-identifier: apply_patch.py
      target: README.md
      checks: [generated-hash, repository-freshness, path-containment, target-before-hash]
    assertion-type: observed
    confidence: high
    evidence:
      - path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
        source-kind: implementation
        symbol: main
        line-start: 22
        line-end: 67
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 141
        line-end: 148
  - id: F-BENCH-001
    category: limitation
    key: quality-superiority
    value:
      current-status: not-run
      claim-policy: prohibited-until-benchmark-pass
      benchmark: benchmarks/quality-benchmark.yaml
    assertion-type: declared
    confidence: high
    evidence:
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 109
        line-end: 114
      - path: docs/quality-benchmark.md
        source-kind: documentation
        line-start: 3
        line-end: 36
  - id: F-PROOF-001
    category: representative-output
    key: reviewed-patch-showcase
    value:
      path: examples/readme-showcase/README.patch
      media-type: text/x-diff
      source-status: PASS
      sha256: 3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
    assertion-type: declared
    confidence: high
    evidence:
      - path: examples/readme-showcase/provenance.yaml
        source-kind: provenance-record
        line-start: 1
        line-end: 9
  - id: F-CODEX-001
    category: capability
    key: codex-skill-and-cross-tool-support
    value:
      skill-identifier: requirement-driven-readme
      codex-path-drivers: implemented
      supported-tools: [codex, antigravity, claude]
      claude-antigravity-runtime-equivalence: phase-4-conformance-goal
    assertion-type: derived
    confidence: high
    evidence:
      - path: .agents/skills/requirement-driven-readme/SKILL.md
        source-kind: skill-contract
        line-start: 2
        line-end: 9
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 8
        line-end: 13
      - path: docs/architecture.md
        source-kind: documentation
        line-start: 32
        line-end: 34
  - id: F-RUN-LAYOUT-001
    category: layout
    key: run-directory
    value:
      canonical: "runs/<repo-id>/<run-id>/"
      public-form: "runs/<repo-id>/<run-id>"
    assertion-type: declared
    confidence: high
    evidence:
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 137
        line-end: 139
      - path: .agents/skills/requirement-driven-readme/SKILL.md
        source-kind: skill-contract
        line-start: 38
        line-end: 39
  - id: F-REPO-LAYOUT-001
    category: layout
    key: repository-paths
    value:
      implementation: src/readme_harness
      rules-and-workflows: .agents
      tests: tests
      request-file: readme-request.yaml
    assertion-type: derived
    confidence: high
    evidence:
      - path: harness.yaml
        source-kind: project-manifest
        line-start: 132
        line-end: 139
      - path: pyproject.toml
        source-kind: build-manifest
        line-start: 14
        line-end: 19
      - path: docs/architecture.md
        source-kind: documentation
        line-start: 7
        line-end: 49
  - id: F-SAFETY-001
    category: safeguard
    key: stale-secret-and-path-protection
    value:
      stale-snapshot: blocks-patch-generation-and-apply
      secret-values: forbidden-in-facts-and-readme
      target-path: must-resolve-inside-repository
      out-of-tree-symlinks: findings-not-traversal-targets
    assertion-type: observed
    confidence: high
    evidence:
      - path: .agents/skills/requirement-driven-readme/scripts/generate_patch.py
        source-kind: implementation
        line-start: 46
        line-end: 68
      - path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
        source-kind: implementation
        line-start: 46
        line-end: 61
      - path: .agents/rules/repository-content-trust.md
        source-kind: policy
        line-start: 13
        line-end: 28
commands:
  - id: CMD-001
    command: python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
    cwd: .
    source:
      path: .agents/skills/requirement-driven-readme/scripts/apply_patch.py
      source-kind: implementation
    verification:
      status: discovered
      method: python-script-existence
  - id: CMD-002
    command: python3 -m pip install -e ".[dev]"
    cwd: .
    source:
      path: pyproject.toml
      source-kind: build-manifest
    verification:
      status: declared
      method: pyproject-optional-dependencies
  - id: CMD-003
    command: python3 -m pytest -q
    cwd: .
    source:
      path: pyproject.toml
      source-kind: build-manifest
    verification:
      status: declared
      method: pytest-configuration