next-step
diff --git a/‎.claude/context/README.md‎
Lines changed: 63 additions & 0 deletions b/‎.claude/context/README.md‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎.claude/context/categories.md‎
Lines changed: 44 additions & 0 deletions b/‎.claude/context/categories.md‎
Lines changed: 44 additions & 0 deletions
diff --git a/‎.claude/context/data-model.md‎
Lines changed: 67 additions & 0 deletions b/‎.claude/context/data-model.md‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎.claude/context/design-principles.md‎
Lines changed: 82 additions & 0 deletions b/‎.claude/context/design-principles.md‎
Lines changed: 82 additions & 0 deletions
diff --git a/‎.claude/context/security.md‎
Lines changed: 40 additions & 0 deletions b/‎.claude/context/security.md‎
Lines changed: 40 additions & 0 deletions
@@ -0,0 +1,63 @@
+# .claude/context — 정본(Single Source of Truth) 컨텍스트
+
+이 폴더는 **여러 스킬·서브에이전트가 공통으로 참조하는 "사실"을 한 곳에 모은 정본**이다.
+같은 지식이 스킬·에이전트·셸 스크립트에 복붙되어 "하나 바꾸면 전부 손봐야 하는" 문제를
+없애기 위해 존재한다.
+
+## 폴더 성격 구분
+
+이 프로젝트의 `.claude` 하위는 성격으로 나뉜다. 헷갈리지 않게 정리한다.
+
+| 폴더 | 성격 | 예 |
+|------|------|-----|
+| `skills/_shared/*.sh` | **실행되는 것** (코드) | `classify.sh`가 돌아감 |
+| `skills/_shared/*.md` | **호출되는 것** (에이전트 프롬프트) | `classifier-agent.md`를 Agent 도구가 prompt로 씀 |
+| **`context/*.md`** | **읽히는 것** (참조 사실) | `data-model.md`를 스킬이 Read해서 참고 |
+
+## 정본 목록
+
+| 파일 | 담는 것 | 로딩 |
+|------|---------|------|
+| [`data-model.md`](./data-model.md) | todos 스키마 + 저장 구조(캐시·outbox·자격증명 경로) | Lazy |
+| [`categories.md`](./categories.md) | 카테고리 6종 정의 + 분류 규칙 | Lazy |
+| [`status-lifecycle.md`](./status-lifecycle.md) | 상태 전이(draft→planned→done) + 스킬별 담당 | Lazy |
+| [`design-principles.md`](./design-principles.md) | 오케스트레이터 패턴·로컬우선동기 등 설계 어휘 | Lazy |
+| [`security.md`](./security.md) | 비밀값 취급 규칙 + 민감 파일 목록 | **Eager** |
+
+## 연결 방식 (하이브리드 — Lazy 기본 + 안전 정본만 Eager)
+
+정본은 두 방식으로 주입된다. 파일 성격에 따라 나뉜다.
+
+### Lazy (기본) — 필요할 때만 Read
+
+대부분의 정본은 **각 스킬/서브에이전트가 필요할 때 Read**한다. CLAUDE.md에 항상 주입하지
+않으므로, 해당 스킬을 실행할 때만 로드되어 평상시 토큰 비용이 없다. 단, 로드 트리거가
+모델의 지시 준수라 100% 보장은 아니다(모델 주도 Lazy 로딩).
+
+각 SKILL.md / 서브에이전트 프롬프트 상단에는 아래처럼 참조가 걸려 있다.
+
+```markdown
+> **참조 정본**: 이 스킬은 아래 정본을 따른다. 관련 판단 시 먼저 Read한다.
+> - `.claude/context/data-model.md`
+> - `.claude/context/status-lifecycle.md`
+```
+
+### Eager (안전 정본) — CLAUDE.md로 상시 주입
+
+`security.md`처럼 **"안 읽으면 사고"가 나는, 무조건 보장이 필요한** 정본은 프로젝트
+`CLAUDE.md`에서 `@import`로 매 세션 항상 로드한다. 특정 스킬 실행과 무관하게 컨텍스트에
+있으므로, 각 스킬은 이를 별도 Read하지 않는다.
+
+```markdown
+<!-- 프로젝트 CLAUDE.md -->
+@.claude/context/security.md
+```
+
+> **승격/강등 기준**: "빈도가 높다"만으로 Eager로 올리지 않는다(길면 매 세션 토큰 낭비).
+> "안 읽었을 때의 리스크가 크고 + 파일이 짧다"가 Eager의 조건이다.
+
+## 규칙
+
+- 정본을 바꿀 때는 **이 폴더의 파일을 먼저** 고친다. 그다음 그 정본의 "코드 표현"
+  (예: `classify.sh`)이나 요약이 어긋났으면 최소 diff로 맞춘다.
+- 새 정본을 추가하면 이 README의 목록과, 참조하는 스킬의 상단 블록을 함께 갱신한다.
@@ -0,0 +1,44 @@
+# 분류 규칙 정본 — 할일 카테고리 6종
+
+> **이 파일의 역할**: 할일 `category`의 유일한 출처. 지금까지 이 규칙은 세 곳
+> (capture SKILL Step 2 표 · `_shared/classifier-agent.md` · `_shared/classify.sh`)에
+> 복제돼 있었다. 이제 **이 파일이 정본**이고, 나머지는 이 파일을 참조하거나(md) 이 파일의
+> 코드 표현(bash)으로 취급한다. 규칙을 바꾸면 이 파일을 먼저 고친다.
+
+## 카테고리 정의
+
+| 카테고리 | 해당 키워드 예시 |
+|---------|---------------|
+| **스터디** | 강의, 책, 자격증, 세미나, 공부, 학습, 과제, 읽기 |
+| **업무** | 미팅, 리포트, 데드라인, 리뷰, 회의, PR, 발표, 제안서 |
+| **일상** | 장보기, 청소, 약속, 취미, 쇼핑, 요리, 빨래 |
+| **건강** | 병원, 운동, 약, 검진, 헬스, 산책, 수면 |
+| **금융** | 납부, 이체, 세금, 보험, 카드, 환전, 저축 |
+| **기타** | 위 카테고리에 해당하지 않는 것 |
+
+`category` 필드에는 이 6개 값 중 **하나의 한글 단어**만 들어간다.
+다른 값을 쓰지 않는다 → 스키마는 [`data-model.md`](./data-model.md).
+
+## 분류 규칙
+
+1. **가장 가까운 카테고리 하나**를 고른다.
+2. **두 카테고리에 걸치면 더 구체적인 쪽**을 고른다.
+   (예: "헬스장 등록비 납부" → 금융이 아니라 **건강**)
+3. **확실하지 않으면 `기타`**.
+4. 분류 결과에 **설명을 덧붙이지 않는다** — 카테고리 이름 한 단어만.
+
+## 이 규칙을 쓰는 세 표현 (모두 동기화 대상)
+
+같은 규칙이 실행 경로에 따라 세 가지로 나타난다. 하나를 바꾸면 셋을 함께 갱신한다.
+
+| 표현 | 위치 | 언제 쓰나 |
+|------|------|-----------|
+| **이 파일** | `context/categories.md` | 정본 — 규칙의 기준 |
+| 메인 인라인 분류 | `capture/SKILL.md` Step 2 | 대화형 `/capture` (메인 모델이 표 보고 직접) |
+| 서브에이전트 프롬프트 | `_shared/classifier-agent.md` | Agent 도구로 분류 위임 시 |
+| bash 사전 분류 | `_shared/classify.sh` | 텔레그램 경로 (모델 없이 ~0.03s) |
+
+> **왜 bash 표현이 따로 있나**: 텔레그램 경로는 `claude -p` 콜드 스타트(~10s)를 우회해야
+> 노티스가 2초 안에 나간다. 그래서 모델 대신 사전으로 분류한다. 대표 키워드는 정확하지만
+> 한 글자 모호어(예: "약")는 놓칠 수 있는 의도된 트레이드오프이며, 나중에 `/plan`에서
+> 카테고리를 조정할 수 있다. 설계 배경은 [`design-principles.md`](./design-principles.md).
@@ -0,0 +1,67 @@
+# 데이터 정본 — todos 스키마 & 저장 구조
+
+> **이 파일의 역할**: 이 OS가 다루는 유일한 데이터인 "할일(todo)"의 형태와 저장 위치를
+> 한 곳에 못 박는다. capture·plan·done·list·remind 는 전부 이 데이터를 읽고 쓰므로,
+> 스키마가 궁금하면 각 스크립트를 역추적하지 말고 **이 파일 하나**를 본다.
+> (연결 방식 = 각 스킬이 필요할 때 이 파일을 Read — `context/README` 참고)
+
+## 1. 할일(todo) 스키마
+
+할일 1건은 아래 필드를 가진 flat JSON 객체다.
+
+| 필드 | 타입 | 필수 | 의미 |
+|------|------|:---:|------|
+| `id` | string (uuid) | ✅ | 고유 식별자. 로컬 생성 시 임시 id, Notion 반영 후 page id 부여 |
+| `title` | string | ✅ | 할일 제목 (캡처 키워드 그대로) |
+| `category` | enum | ✅ | 6종 중 하나 → [`categories.md`](./categories.md) |
+| `status` | enum | ✅ | `draft` \| `planned` \| `done` → [`status-lifecycle.md`](./status-lifecycle.md) |
+| `captured_at` | ISO8601 | ✅ | 캡처 시각. 한국 시간대(`+09:00`). 스크립트가 자동 기록 |
+| `recurrence` | null \| string | | 반복 규칙. `null`(1회) \| `"once"` \| `"daily"` 등 |
+| `due_date` | null \| date(YYYY-MM-DD) | | 마감일. 미정이면 `null` |
+| `time` | null \| string | | 시각/시간대 (예: `"저녁"`, `"09:00"`). 미정이면 `null` |
+| `detail` | null \| string | | 구체화 내용. `"이유: ...\n방법: ..."` 형식. plan 단계에서 채워짐 |
+
+### 예시
+
+```json
+{
+  "id": "38b079ad-1f35-81e7-8b21-c872361b519e",
+  "title": "장보기",
+  "category": "일상",
+  "status": "planned",
+  "captured_at": "2026-06-25T10:00:00.000+09:00",
+  "recurrence": null,
+  "due_date": "2026-06-25",
+  "time": null,
+  "detail": "이유: 냉장고가 비었음\n방법: 마켓 직접 방문"
+}
+```
+
+### 불변 규칙
+
+1. **필드 직렬화는 flat JSON 배열** — 중첩 없이 위 필드만.
+2. **`detail`의 줄바꿈은 `\n` 문자열로 보존** — 저장 시 `echo` 금지, `printf '%s'` 사용
+   (zsh `echo`는 `\n`을 실제 개행으로 바꿔 JSON을 깨뜨린다).
+3. **`captured_at`은 사람이 손대지 않는다** — 캡처 스크립트가 채우는 값.
+
+## 2. 저장 구조 (정본 = Notion, 로컬 = 캐시/버퍼)
+
+원격 정본은 **Notion**이고, 로컬은 속도를 위한 read-model(캐시) + write 버퍼(outbox)다.
+"로컬-우선 + 백그라운드 동기" 설계는 [`design-principles.md`](./design-principles.md) 참고.
+
+| 경로 | 성격 | 쓰는 주체 |
+|------|------|-----------|
+| `.claude/data/cache/todos.json` | **로컬 read-model** — list/done 조회의 출처 | `cache.sh`, `done-fast.sh` |
+| `.claude/data/cache/pending-done.json` | 완료 대기 큐 (백그라운드 동기용) | `done-fast.sh` |
+| `.claude/data/outbox/` | capture write 버퍼 (유실 방지, 재시도) | `capture-fast.sh`, `capture-flush.sh` |
+| `.claude/data/notion.json` | Notion 자격증명 **(비밀값·gitignore)** | 읽기 전용 → [`security.md`](./security.md) |
+| `.claude/data/telegram.json` | 텔레그램 자격증명 **(비밀값·gitignore)** | 읽기 전용 → [`security.md`](./security.md) |
+
+### 읽기/쓰기 경로 요약
+
+- **읽기(list·done·plan·remind)**: `cache.sh` / `notion.sh read` — 크리티컬 패스에 네트워크 없음.
+- **쓰기(capture)**: `capture-fast.sh` → outbox 즉시 + Notion 백그라운드.
+- **완료(done)**: `done-fast.sh complete` → 캐시 즉시 반영 + Notion 백그라운드.
+
+> 캐시가 아예 없는 최초(cold)에만 동기 네트워크를 타며, SessionStart 훅(`cache.sh refresh-bg`)이
+> 미리 데워 이를 제거한다.
@@ -0,0 +1,82 @@
+# 설계 원칙 정본 — 이 OS를 "이 OS답게" 만드는 판단 기준
+
+> **이 파일의 역할**: 이 프로젝트가 반복해서 따르는 설계 어휘를 모은다. 데이터가 아니라
+> **"어떻게 만들지 판단하는 기준"**이다. 새 스킬을 짜거나, state-sync-writer·sync-readme·
+> sync-test 같은 문서/리팩터 서브에이전트가 코드를 만질 때 이 원칙과 어긋나지 않게 한다.
+
+## 1. 오케스트레이터 패턴 — 스킬은 얇게, 일은 위임
+
+SKILL.md는 **"무엇을 할지"만 결정하는 얇은 조율자**다. 실제 일(분류·저장·포맷·발송)은
+공유 스크립트(`_shared/*.sh`)나 서브에이전트(`_shared/*.md`)가 한다.
+
+- 가벼운 판단(키워드 1개 → 카테고리 1개)은 **오케스트레이터가 흡수**한다.
+- 무거운 일(추론·대화가 필요한 인터뷰, 메시지 작성)만 **서브에이전트에 위임**한다.
+- 같은 책임은 **공유체 하나로 재사용**한다 — 예: 알림 발송은 `telegram-agent`, 정본 갱신은
+  `state-sync-writer` 하나로. 채널/산출물이 바뀌어도 그 파일만 교체하면 된다.
+
+## 2. 로컬-우선 + 백그라운드 동기 — 네트워크를 크리티컬 패스에서 뺀다
+
+사용자 체감 응답에서 네트워크 왕복을 없애는 게 이 OS의 성능 축이다.
+
+- **쓰기**: 로컬 outbox/캐시에 즉시 durable 저장(≈10ms) → 원격(Notion) 반영은
+  detached 백그라운드. 유실 없음(실패 시 outbox에 남아 재시도).
+- **읽기**: 로컬 read-model(캐시)에서 즉시 반환 → stale이면 갱신을 백그라운드로.
+- **cold(캐시 없음)만 예외**로 동기 네트워크를 타며, SessionStart 훅이 미리 데워 제거한다.
+
+구체적 경로는 [`data-model.md`](./data-model.md)의 저장 구조 참고.
+
+## 3. 결정론적 호출은 LLM을 우회한다
+
+입력이 정해지면 출력도 정해지는 일(조회·필터·상태 업데이트·표시 규칙)에는 서브에이전트를
+띄우지 않는다. 콜드 스타트·프롬프트 재독해·curl 조립 추론이 낭비이기 때문.
+
+- 결정론적 → **Bash로 직접 호출** (`notion.sh`, `list-view.sh`, `done-fast.sh` …).
+- 비결정론적(추론·대화 필요) → **Agent 도구로 위임**.
+
+## 4. 단일 출처(Single Source of Truth) + 최소 diff
+
+- 같은 지식/규칙은 한 곳에만 둔다. 그래서 이 `context/` 폴더가 존재한다.
+  표시 규칙은 `list-view.sh`, 분류 규칙은 [`categories.md`](./categories.md)에 모은다.
+- 정본을 갱신할 때는 **전면 재작성이 아니라 어긋난 부분만 최소 diff**로 고친다
+  (state-sync-writer의 불변 규칙). 기존 구조·말투·한국어 톤을 유지한다.
+
+## 5. 정직한 한계 서술
+
+못 하는 것을 숨기지 않는다. 예: "저장을 백그라운드로 빼도, `/capture` 요청을 이해하고
+도구 호출을 발행하는 **모델 추론 턴**은 물리적 바닥이라 end-to-end 1초 보장은 불가능하다."
+스킬이 제어 가능한 범위(네트워크·모델 턴 수)를 최적화하되, 물리적 한계는 명시한다.
+
+## 6. 비밀값은 절대 노출하지 않는다
+
+자격증명(토큰·chat_id 등)은 gitignore된 파일에서만 읽고, 로그·응답·커밋에 전문을 쓰지
+않는다. 상세는 [`security.md`](./security.md).
+
+## 7. 로컬 저장소는 "목표 상태"로 구분한다 — 캐시 · 버퍼 · 축적
+
+§2의 로컬-우선 전략은 데이터를 여러 로컬 파일에 쌓는다. 그런데 "로컬에 쌓인다"가 같다고
+셋을 뭉뚱그리면 안 된다 — **정상 상태(steady state)가 정반대**이기 때문이다. 어떤 저장소를
+만지기 전에 "이건 셋 중 뭐냐"를 먼저 판정한다.
+
+| 종류 | 목표 상태 | 지우면 | 레포 실체 |
+|------|----------|--------|-----------|
+| **캐시** | 원본과 일치하는 거울 | 재생성됨(무해) | `data/cache/todos.json` — "지워도 되는 순수 Notion 스냅샷" |
+| **버퍼** | **비어 있음(0)** | **유실됨** | `data/outbox/*.json`, `pending-done.json` — 아직 동기 안 된 생성·완료 |
+| **축적 저장소** | 끝없이 성장 | 과거가 사라짐 | `skill-invocations.log` — append-only, 커질수록 가치 |
+
+- **캐시**는 원본(Notion)의 파생물이라 삭제해도 재생성된다. 목표는 "원본과 일치".
+- **버퍼**는 정반대로 **비어야 정상**이다. 값을 담고 있는 건 "아직 처리 못 함"의 표시일 뿐,
+  성공하면 사라진다. 그래서 버퍼는 지우면 원본이 유실된다.
+- **축적 저장소**만 "커질수록 가치"다. 드레인하지 않고 계속 append 한다.
+
+### 루프도 이 축으로 갈린다 — 탐지형 vs 축적형
+
+- **자율탐지형(조정) 루프**: "이상/미처리 있나?"를 주기적으로 감지해 반응하고 잊는다.
+  잘 돌수록 조용하다. 버퍼를 **0으로 드레인**하거나 데몬을 지키는 루프가 여기 속한다 —
+  `flush-cron`(outbox 재동기), `watchdog-cron`(데몬 헬스), `digest-cron`(방치 draft 탐지).
+- **자산 축적형 루프**: 매 반복이 성장하는 저장소에 한 겹씩 쌓고, 그 축적물을 나중에 회수해
+  더 큰 가치를 낸다. **write 절반과 read 절반이 쌍**을 이룬다 — 이 레포의 유일한 순수 예는
+  **자기 관찰 루프**(로그 write 훅 → `/usage` read)다.
+
+> 흔한 혼동: capture의 로컬 저장부는 **캐시 + 버퍼**이지 축적이 아니다. outbox는 목표가
+> "0"이라 축적과 정반대고, outbox 자체는 데이터일 뿐 루프는 그걸 드레인하는 `flush-cron`
+> (탐지형)이다. "로컬에 쌓인다"만 보고 축적형 루프라 부르지 않는다.
@@ -0,0 +1,40 @@
+# 비밀값 규칙 정본 — 자격증명 취급
+
+> **이 파일의 역할**: 짧지만 치명적인 규칙. 자격증명을 만지는 모든 경로(telegram-agent,
+> notion.sh, 리스너, 디버깅 중인 서브에이전트)가 공통으로 지킨다. 지금까지 이 규칙은
+> telegram-agent.md 안에만 부분적으로 있었다 — 교차 관심사라 별도 정본으로 뺀다.
+
+## 민감 파일 (모두 `.gitignore` 대상 — 커밋 금지)
+
+| 파일 | 내용 |
+|------|------|
+| `.claude/data/telegram.json` | 텔레그램 봇 토큰, chat_id |
+| `.claude/data/notion.json` | Notion API 자격증명 |
+| `.claude/data/telegram-offset.txt` | 리스너 폴링 오프셋 (로컬 런타임) |
+| `.claude/data/telegram-listener.log` | 리스너 로그 (로컬 런타임) |
+| `.claude/data/cache/`, `.claude/data/outbox/` | 사용자 개인 할일 데이터·로컬 캐시 |
+| `.claude/skill-invocations.log` | 스킬 호출 로그 (로컬 런타임) |
+| `.claude/data/watchdog-state.txt`·`watchdog.log`·`flush-cron.log`·`digest-cron.log` | 시스템 루프(감시·flush·집계) 런타임 상태·로그 |
+
+이 목록은 `.gitignore`와 일치해야 한다. 새 비밀값 파일을 추가하면 **양쪽을 함께 갱신**한다.
+
+## 불변 규칙
+
+1. **토큰·chat_id 전문을 출력하지 않는다** — 로그, 사용자 응답, 커밋, 에러 메시지 어디에도.
+   실패 응답에도 노출 금지 (예: `{ "ok": false, "error": "토큰 없음" }` — 값은 싣지 않는다).
+2. **자격증명 파일은 읽기 전용으로만 접근** — 위 파일에서 값을 읽어 API를 호출할 뿐,
+   내용을 다른 파일·로그로 복사하지 않는다.
+3. **파일이 없거나 비어 있으면 발송/호출하지 않고 실패를 응답한다.**
+4. **개인 할일 데이터(cache/outbox)를 커밋하거나 외부로 내보내지 않는다.**
+
+## 자격증명 사용 예 (telegram)
+
+```bash
+# .claude/data/telegram.json 에서 읽어 API 호출 — 값을 로그에 남기지 않는다
+curl -s "https://api.telegram.org/bot<bot_token>/sendMessage" \
+  --data-urlencode "chat_id=<chat_id>" \
+  --data-urlencode "text=<메시지>" \
+  -w "\n%{http_code}"
+```
+
+> 이 원칙은 [`design-principles.md`](./design-principles.md) §6과 같은 규칙의 상세판이다.