ABAP-Indexing/docs/okf-version.md

# OKF 스펙 버전 고정 기록 (계획서 v4 §10.11)

- **채택 버전**: OKF v0.2
- **확인일**: 2026-08-26
- **원문**: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
- (v0.1: 2026-06-12 공개 / v0.2: 2026-07-25 — 신뢰 필드 추가)

## 확인된 스펙 요지

- 필수 필드는 `type` 하나. 권장: `title`, `description`, `resource`, `tags`.
- 신뢰/수명 필드(선택): `generated: {by, at}`, `verified: [{by, at}]`(단일 매핑도 1원소 리스트로 해석),
  `sources`(provenance), `status: draft|stable|deprecated`(기본 stable), `stale_after`.
- actor 표기: 에이전트/도구 `<producer>/<version>`, 사람 `human:<id>`, 프로세스 `process:<id>`.
- **확장 필드 자유** — 소비자는 미지 키를 보존해야 하고, 없는 선택 필드 때문에 거부하면 안 됨.
- 예약 파일: 번들 루트 `index.md`(매니페스트, `okf_version: "0.2"` frontmatter), `log.md`.
  → 구 계획(v3)의 `okf.yaml` 매니페스트는 **index.md 로 대체**.
- 링크: 표준 마크다운 링크. `/` 로 시작하면 번들 루트 상대(권장 — 문서 이동에 안정적).

## 계획서 x- 필드 → v0.2 표준 필드 매핑 (확정)

| 구 계획(v3) | 채택(v4) | 비고 |
|---|---|---|
| `x-human-edited: true` | `verified: { by: "human:<id>", at: <ISO-8601> }` | 사람이 검토·수정 후 저장할 때 추가. merge.py 는 구 규약도 하위호환 인식 |
| (없음) | `generated: { by: "abap-indexing/<모델>", at: ... }` | 생성 주체. 요약 전 구조 문서는 `abap-indexing/parser` |
| 재검토 필요 표시 | `status: draft` + `wiki/_review.md` | 코드 해시 변경 시 merge.py 가 설정 |
| `x-confidence`, `x-prompt-version`, `x-program` 등 사실 필드 | **x- 확장 유지** | 표준에 대응 없음 — 스펙이 확장 키를 허용 |
| `okf.yaml` | `index.md` (예약 파일) | wiki_out/okf_writer.py `write_manifest` |

## 구현 위치

- 출력: `wiki_out/okf_writer.py` / 병합: `wiki_out/merge.py` / 검증: `python -m wiki_out.validate`
- frontmatter 의 관리 대상(배치가 갱신하는) 필드는 `merge.MANAGED_KEYS` — 모두 한 줄 YAML 로 emit.

## 2026-09-16 변경 — 문서 단위

- unit 별 개별 문서(`units/`, `type: abap-unit`)는 생성하지 않는다.
- LLM 이 골라낸 로직 조각은 프로그램 문서(`type: abap-program`) 안의 `## 로직 조각` 섹션이다.
  조각마다 resource 는 `abap://<PROG>/<INCLUDE>#L<from>-L<to>` 형식으로 본문에 적는다.
- 확장 필드 `x-chunk-count` 추가. 설계 근거는 `docs/logic-chunk-design.md`.