/knowledge-wiki

name: knowledge-wiki
description: 세션에서 배운 것을 정책 게이트를 통과시켜 팀 위키에 자동 축적한다. github.com/wigtn/ repo 작업은 폴더 위치와 무관하게 팀 위키(wigtn-team-wiki)로 가고, 그 외는 전역 설정(~/.config/wigtn/knowledge-wiki.yml)에 지정한 경로에서만 동작하며, 시크릿·개인정보·고객 식별 정보는 4단 게이트로 차단한다. 쌓인 기록 중 프롬프트와 관련 있는 글은 자동으로 컨텍스트에 붙인다. 위키 설정·정책 확인·수동 축적·문제 진단에 사용한다.
allowed-tools: Read, Write, Edit, Glob, Bash

Knowledge Wiki

세션 지식을 **일반화된 article**로 컴파일해서 팀 위키에 쌓는다. Karpathy KB 패턴 — 매번 찾는 게 아니라 위키 자체가 자란다.

> **한 줄**: 세션에서 *배운 것*만 쌓는다. *있었던 일*은 쌓지 않는다.

켜는 법

**WIGTN repo 는 설치만 하면 됩니다.** remote 가 `github.com/wigtn/` 인 repo 에서 작업하면 팀 위키로 쌓이고, 처음 한 번 안내가 나옵니다:

[wigtn] github.com/wigtn/ repo 작업에서 배운 것을 팀 위키로 보냅니다 → wigtn-team-wiki/per-user/<사용자>
        WIGTN repo 밖에서는 아무것도 하지 않습니다.

**그 외 repo 에서는 아무것도 하지 않습니다.** 설정 파일도 위키 폴더도 만들지 않고 LLM 도 부르지 않습니다. 개인 위키를 쓰려면 `~/.wigtn/knowledge-wiki.yml` 에 `wiki`·`include` 를 적습니다 (아래 "범위 조정"). `remote` 가 없으면 push 하지 않습니다.

0.1.21 까지는 설정이 없으면 홈 전체를 로컬에 쌓는 설정을 자동으로 만들었습니다. 그 파일을 손대지 않고 두었다면 `include` 는 무시합니다 (`enabled`·`exclude` 는 그대로 지킵니다).

WIGTN repo 는 설정 없이 팀 위키로

remote 가 `github.com/wigtn/` 인 repo 의 작업은 아래 `wiki`·`include` 설정과 상관없이 팀 위키 `wigtn/wigtn-team-wiki` 의 `per-user/<사용자>/` 로 push 됩니다. 개인 fork 라도 `upstream` 이 팀 repo 면 같습니다. 폴더를 어디에 두든, 디렉터리 구조가 어떻든 결과가 같습니다.

• 위키는 `~/.wigtn/wigtn-team-wiki` 에 자동 clone 됩니다. 전역 설정의 `wiki` 가 이미 팀 위키를

가리키면 그 경로를 그대로 씁니다. clone 은 작업 repo 와 같은 방식(SSH 또는 HTTPS)을 씁니다.

• 필요한 것은 팀 위키 repo 쓰기 권한과 git 인증뿐입니다.
• 팀 위키를 못 받으면 그 세션 기록은 버리고(다른 위키로 넘기지 않음), 사유를 `~/.wigtn/state/.knowledge-wiki.log` 에 남깁니다.
• 빼고 싶은 repo 는 `exclude`, 전체 중지는 `enabled: false` 입니다. 둘 다 팀 라우팅보다 강합니다.

팀과 공유하려면 — remote 한 줄

wiki:
  remote: git@github.com:myteam/team-wiki.git   # 추가하면 push 시작
  path: ~/Dev/team-wiki                          # 없는 경로면 자동 clone
  subdir: per-user/harry

`path` 가 없고 `remote` 가 있으면 **자동으로 clone** 합니다. 새 팀원은 이 두 줄만 받으면 됩니다. clone 실패 시에는 축적하지 않습니다 (fail-closed).

범위 조정

include:            # 쌓을 경로. 비어 있으면 WIGTN repo 밖에서는 아무것도 안 한다
  - ~/Dev
exclude:            # 고객사·NDA repo. include 와 repo 마커보다 강하다
  - ~/Dev/client-nda

**`remote` 가 있어도 `include` 가 홈/루트 전체면 push 는 보류됩니다.** 글은 위키 폴더에 파일로만 남고(커밋하지 않음), 로그에 사유가 남습니다. `include` 를 좁히면 그때 push 가 켜집니다. 로컬 축적과 팀 공유는 위험도가 다르고, 그 경계는 권고가 아니라 코드가 집행합니다.

`subdir` 은 `per-user/` 아래만 허용됩니다. `shared/` 는 사람이 PR 로 승격합니다.

템플릿: `scripts/knowledge_wiki/knowledge-wiki.example.yml`

repo 마커 (선택) — 예외 처리용

보통은 필요 없다. 아래 세 경우에만 repo 루트에 `.wigtn-wiki.yml` 을 둔다:

| 상황 | 마커 내용 | |---|---| | `include` 밖 repo를 개별 opt-in | `enabled: true` | | 이 repo만 다른 위키로 | `wiki: {path: ..., subdir: ...}` | | 이 repo만 끄기 | `enabled: false` |

⚠️ **전역 `exclude` 와 전역 `enabled: false` 는 마커보다 강하다.** exclude 된 경로, 그리고 전역으로 꺼 둔 상태는 마커가 있어도 거부된다. 마커는 *범위 opt-in* 이지 *kill-switch 해제* 가 아니다.

어떻게 동작하나

세션 종료(Stop 훅) 시 4단 게이트를 통과한 것만 커밋·push 된다.

G0 스코프 게이트   팀 org repo는 팀 위키로, 그 외 include 밖·exclude·자기오염이면 즉시 종료
G1 결정론 차단    원문에 키·자격증명·주민번호 → 1건이라도 hit면 세션 폐기
G2 LLM 컴파일     transcript → 일반화 article (원문 인용 금지, 분야는 범례에서, 태그는 기존 것 우선)
G3 LLM 감사       별도 호출로 반출 위반 탐지 (통과 판정 권한 없음)
G4 결정론 재검사   article에 전체 패턴 적용 — 이메일·사설 IP·절대경로까지
     ↓
per-user/ 커밋 + push

**모든 실패는 폐기다.** 판정 불가·타임아웃·파싱 실패 전부 버린다. 위키 항목 하나 잃는 건 싸고, 유출은 되돌릴 수 없다.

정책 정본: [`../../contracts/INGEST-POLICY.md`](../../contracts/INGEST-POLICY.md)

분야 범례

G2 는 글마다 아래 범례에서 분야를 **하나** 고르고, 그 값은 글의 frontmatter `type` 이 된다. openwiki visualize 는 `type` 으로 노드 색과 범례를 정하므로, 위키 그래프의 범례가 곧 이 표다. 이름은 [estudy](https://github.com/rlaope/estudy) 의 상위 분류를 따르고, 거기 없는 `Research` 만 더했다. 범례에 없는 값이 나오면 버린다 (글은 남고 frontmatter 만 없다). 정본은 `scripts/knowledge_wiki/compile.py` 의 `FIELDS`.

| 분야 | 범위 | |---|---| | AI | LLM·에이전트·프롬프트, 모델 평가와 LLM 심사자, 생성 모델 활용 | | MLOps | 모델 서빙·추론 엔드포인트, ML 파이프라인, 에이전트 실행 인프라 | | Back-End | 서버·API, 언어·런타임·라이브러리 동작, 동시성·캐싱, 신호·음성 처리, 백엔드 테스트 | | Front-End | 웹 UI·레이아웃·CSS, JS/TS·React/Next.js, 정적 사이트, 폰트·SVG·접근성 | | DevOps | git·GitHub(브랜치·PR·ruleset), CI/CD·자동화 파이프라인, 배포·호스팅, 컨테이너·클라우드 | | DataBase | DB·쿼리·스키마, 트랜잭션, 데이터 적재·무결성 | | Design-Pattern | 설계 판단·아키텍처·모듈 경계, 의사결정 기록(ADR), 정보 구조 | | SRE | 운영·장애 대응, 모니터링, 신뢰성, 성능 측정 | | Algorithm | 알고리즘·자료구조 | | Math | 통계·확률·추정 방법 자체, 수치 계산 | | Research | 실험·측정 설계, 결과 해석과 보고, 논문 작성·LaTeX, 그림·포스터, 재현성, 학회 심사 |

쌓은 것을 다시 꺼내 쓴다

| 시점 | 훅 | 하는 일 | |---|---|---| | 세션 시작 | SessionStart (비동기) | 위키 pull, 지난 세션에 못 보낸 커밋 push. 위키가 없으면 clone | | 프롬프트마다 | UserPromptSubmit | 관련 글 최대 3건의 제목·요약 한 줄을 컨텍스트에 붙인다 (1,200자 이내) | | 응답 끝 | Stop (비동기) | 위 4단 게이트 → `per-user/` 커밋·push. 거부되면 pull 후 한 번 더 |

회상은 **이 repo가 기록을 보내는 위키에서만** 읽는다 (G0와 같은 판정). 그래서 exclude 된 repo에는 팀 지식이 들어가지 않는다. 팀원 전원의 `per-user/`와 `shared/`를 검색하고, 같은 글은 세션당 한 번만 붙인다. 관련성이 낮으면 아무것도 붙이지 않는다.

사용자가 할 일

**두 가지뿐이다.**

1. **아무것도 안 함.** WIGTN repo 작업은 팀 위키로 올라가고, 그 외 repo 에서는 아무 일도 없다 2. 개인 위키를 원하면 설정 파일에 경로를 적고, 공유할 글은 `per-user/` 에서 **PR로 `shared/` 승격**

항목별 검토는 안 해도 된다. 그게 정책의 목적이다.

진단

축적이 안 될 때 확인 순서:

# 1. 전역 설정이 있나 / include 에 이 경로가 들어있나
cat ~/.config/wigtn/knowledge-wiki.yml 2>/dev/null || cat ~/.wigtn/knowledge-wiki.yml

# 2. 게이트 통과 여부 — 위키 repo의 로그
tail -20 <wiki>/.knowledge-wiki.log

로그 예시와 의미:

| 로그 | 뜻 | 조치 | |---|---|---| | (로그 자체가 없음) | G0에서 종료 — include 밖/exclude/자기오염 | `~/.wigtn/knowledge-wiki.yml` 확인 | | `G1 폐기: D1 API 키` | 세션에 시크릿이 있었다 | 정상 동작. 조치 불필요 | | `G2 폐기: 기록 가치 없음` | 단순 작업 세션 | 정상 동작 | | `G3 폐기: 위반 탐지 D3` | 고객 식별 정보 등이 남아 있었다 | 정상 동작 | | `G4 폐기` | LLM이 금지 항목을 되살렸다 | 정상 동작 | | `게시 … (커밋하지 않고 파일만 저장) — push 보류: include 범위가 홈/루트 전체` | 파일로만 남겼다 | `include` 를 좁히면 켜진다 | | `~/.wigtn/state/.knowledge-wiki.log` 의 `G0 거부: 팀 위키 확보 실패` | WIGTN repo인데 팀 위키를 못 받았다 | 팀 위키 repo 권한·git 인증 확인 | | `게시 … (커밋됨, push 실패: …)` | pull 후 재시도도 실패 | 다음 세션 시작 때 다시 보낸다. 반복되면 git 인증 확인 | | `동기화: 작업 중인 변경이 있어 pull 생략` | 위키를 손으로 고치는 중 | 커밋하거나 되돌리면 다음 세션부터 동기화 | | `게시 실패` | git 문제 | 위키 repo 권한·remote 확인 |

**폐기 로그가 많은 건 문제가 아니다.** 게이트가 일하고 있다는 뜻이다.

수동 축적

훅을 기다리지 않고 지금 쌓고 싶으면:

echo '{"cwd":"'$PWD'","transcript_path":"<transcript.jsonl>"}