init: readme 작성 하네스 설계

runs/readme-harness/20260720-public-readme-r2/repository-facts.yaml

@@ -0,0 +1,387 @@
+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