AGENTS.md — wiki2 운영 계약

이 문서는 AI/에이전트가 wiki2에서 어떻게 일하는가를 정의한다.
무엇을 어떤 기준으로 분류하는가는 ontology.md가 유일하게 owner다.

충돌 시: ontology > AGENTS.md > 관행.

0. 역할

주체	한다	하지 않는다
사람	소스 큐레이션, 방향, 좋은 질문, ontology 개정 승인	귀찮은 교차참조 수작업(원하면 가능)
AI	ingest 합성, 페이지 갱신, index/log, lint, 답변 fileback	raw 본문 수정, ontology 무단 개정, 닫힌 집합 밖 값 발명

작업 단위는 작고 검토 가능하게. 한 소스 ingest가 여러 wiki 페이지를 건드려도 된다. 단, 같은 단위에서 index·log를 맞춘다.

1. 세션 시작 체크

ontology.md 축·불변식·허용 표 확인
index.md로 현재 지도 파악
grep "^## \\[" log.md | tail -5 로 최근 작업 확인
사용자 요청이 분류 확장을 요구하면 제안 후 승인 — 단독 개정 금지

2. Ingest

새 지식을 raw에서 위키로 편입한다.

2.1 사전

원본을 raw/inbox/에 둔다 (이미 imports/면 그대로).
corpus를 고른다: project | orbit | reference
origin / domain을 ontology 닫힌 집합에서 고른다.
project 필드가 필요하면 §3.6 목록에 있는지 확인. 없으면 확장 제안 먼저.

2.2 절차

raw 본문을 읽는다. (이미지 있으면 텍스트 후 필요 시 별도 확인)
핵심 takeaway를 사용자와 짧게 맞출 수 있으면 맞춘다. (배치 ingest면 스킵 가능 — 사용자가 지시)
layer: source + type: brief 페이지를 wiki/brief-{slug}.md로 작성한다.
- frontmatter I1 필수 필드
- raw_source (또는 reference면 ref_* )
확정 원본은 raw/inbox/ → raw/imports/ 로 옮기고 raw_source를 갱신한다. (이미 imports면 이동 없음)
관련 model 페이지를 갱신 또는 신설한다.
entity / concept / comparison / thesis / map — 불변식 I7, corpus×type §5.
명확한 결정·교훈이 있으면 judgment 페이지를 별도로. source/model에 결정을 섞지 않는다.
index.md에 항목 추가/수정.
log.md에 ingest 항목 append.

2.3 corpus별 강조

corpus	강조
project	내 repo/문서 raw, owned 위주, 필요 시 external 인용
orbit	외부 클리핑 + 내 분류/연결. 원문 재저술보다 brief+링크
reference	map + brief 중심. 본문 확장·재해석 금지. pin 유지

2.4 한 소스가 건드릴 수 있는 것

brief 1 + model N + (선택) judgment + index + log.
10~15 페이지를 넘기면 단위를 나누는 것을 권장.

3. Query

위키를 상대로 질문에 답한다.

index.md를 먼저 읽어 후보 페이지를 고른다.
해당 페이지를 읽고 합성한다. 답에 wiki 경로 인용.
raw가 필요하면 brief의 raw_source로만 내려간다. (매 질문 full-RAG 금지 — 위키가 컴파일 층)
fileback: 재사용할 답·비교·연결은 wiki/query-{slug}.md 또는 적합한 type으로 남긴다.
- layer/type은 내용에 맞게 (순수 탐색 요약이면 model+query, 내 입장이면 judgment+query/decision/learning)
fileback 했으면 index + log (query) 갱신.

답이 일회성이고 얇으면 fileback 생략 가능. 사용자가 남기라고 하면 남긴다.

4. Lint

주기적 건강 점검. 사용자가 요청하거나 ingest 연속 후 권장.

4.1 검사 항목

불변식 I1–I18 (ontology §4)
corpus×type 허용 표 (ontology §5)
깨진 상대 링크
orphan (inbound 없음) — map/index에서 고립
domain: unsorted draft 적체
stale: 더 새 brief가 옛 model/judgment와 모순
reference 페이지의 pin 실효
index에 없는 wiki 페이지 / wiki에 없는 index 항목
project 필드가 빈 목록을 가리킴

4.2 출력

문제 목록 (심각도: block / should / nice)
권장 후속 질문·가져올 소스
log에 lint 항목

자동 수정은 block급 메타(index 누락 등)만 기본.
본문 의미 변경은 제안 후 적용.

5. index.md 규칙

카탈로그. 내용 요약 한 줄 + 링크.
1차 그룹: corpus (project / orbit / reference / meta-ops)
2차 그룹: type 또는 domain (페이지 수 적을 때는 type)
매 ingest·fileback·의미 있는 갱신 때 동기화.
페이지 0개 섹션은 헤더만 두거나 “없음” 한 줄.

6. log.md 규칙

append-only. 헤더 형식:

## [YYYY-MM-DD] {kind} | {short title}

본문 최소:

무엇을
영향 받은 경로 (불릿)
(선택) 다음 액션

조회: grep "^## \\[" log.md | tail -5

7. ontology 개정

사용자 합의
ontology.md 수정
log ontology 항목
필요 시 기존 페이지 마이그레이션 같은 단위

AI 단독 개정 금지. 상세: ontology §7.

8. 토폴로지 변경

폴더 추가/이동은 축 복제가 아니어야 한다.
분류는 frontmatter. 새 폴더는 물리 필요(예: assets 하위)가 있을 때만.

변경 시: 관련 README 체인 갱신 + log topology.

9. 명명·링크

파일: {type}-{slug}.md (wiki/README)
링크: 저장소 루트 기준 또는 상대 경로 Markdown 링크
제목: 짧고 설명적으로

10. 금지 요약

raw 본문 편집
닫힌 집합 밖 값
reference 본문 키우기
judgment를 source/model에 숨기기
index/log 없는 wiki 신설 커밋 단위
사용자 확인 없는 ontology/project 목록 확장
폴더로 corpus/domain 축 미러링

11. 검증

# 통합 검증 (I1–I18, corpus×type, index, log, links, raw_source)
python3 scripts/verify_wiki.py

# 최근 로그
grep "^## \[" log.md | tail -5

# wiki 페이지 목록
find wiki -name '*.md' ! -path 'wiki/README.md' | sort

페이지 추가 후:

python3 scripts/verify_wiki.py 통과
index 항목 존재
log 항목 존재
raw_source / ref_* 유효

12. 개정

날짜	요약
2026-07-18	초안. ingest/query/lint, index/log, ontology 종속
2026-07-18	`scripts/verify_wiki.py` 추가, log kind에 decision