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 전 우월성 주장 금지