hypomnema 1.1.0 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "hypomnema",
       "source": "./",
       "description": "LLM-native personal wiki — session-aware knowledge base for Claude Code",
-      "version": "1.1.0",
+      "version": "1.2.1",
       "homepage": "https://github.com/sk-lim19f/Hypomnema"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "LLM-native personal wiki system — session-aware knowledge base for Claude Code",
   "author": {
     "name": "sk-lim19f",

package/README.ko.md

@@ -15,13 +15,21 @@
 
 **Claude Code를 위한 LLM 네이티브 개인 위키. 복리로 성장하는 지식.**
 
-_Claude가 노트하게 만드세요 — 그리고 그게 실제로 일어나는지 측정하세요._
+_Claude에게 기록을 맡기세요 — 그리고 그 기록이 실제로 쌓이는지 측정하세요._
 
 [빠른 시작](#빠른-시작) • [다른 시스템과의 비교](#다른-시스템과의-비교) • [설계 결정](#설계-결정) • [기능](#기능) • [아키텍처](docs/ARCHITECTURE.md) • [기여](docs/CONTRIBUTING.md)
 
-> Andrej Karpathy의 "LLM 네이티브 위키" 스케치에서 영감을 받아, 10개월간의 개인 운영 경험으로 다듬어진 도구입니다. 캡처 → 합성 → 검색 → 세션 재개로 이어지는 전체 라이프사이클을 Claude Code 명령어와 라이프사이클 훅으로 제공합니다.
+> Andrej Karpathy의 "LLM 네이티브 위키" 스케치에서 영감을 받아, 10개월간의 AI 워크플로우 실험과 v1.2.0 공개 전 한 달의 Hypomnema 직접 굴리기(dogfood)로 다듬어진 도구입니다. 캡처 → 합성 → 검색 → 세션 재개로 이어지는 전체 라이프사이클을 Claude Code 명령어와 라이프사이클 훅으로 제공합니다.
 
-> **현재 상태 vs. v2 비전.** v1.0.1(현재)은 트리거 모델을 정직하게 밝힙니다: 대부분의 위키 동작 — 인제스트, 쿼리, 세션 클로즈 — 은 **명시적 `/hypo:*` 커맨드**로 시작되며, 일부 훅이 자동 staging·세션 상태 주입·룩업 신호를 처리합니다. v2 thesis는 *완전 자율* — Claude가 요청 없이 위키를 읽고·쓰고·합성하는 상태입니다. **v1.1.0**은 그 램프의 첫 단계로, 자율을 주장하는 대신 **observability 점수**를 출력해 세션당 위키가 실제로 얼마나 쓰였는지(ingest 수, query 수, session-close 비율, citation 비율)를 측정·공개합니다. v2 구현 이전에 자율 vs. 수동 비율을 사용자가 직접 확인할 수 있게 하기 위함입니다.
+> **아래에서 자주 쓰이는 용어 간단 정리.** *프런트매터(frontmatter)* = 마크다운 파일 맨 위의 YAML 블록. *위키링크(wikilink)* = `[[페이지-슬러그]]` 형태의 교차 참조. *ADR* = "Architecture Decision Record" — 어떤 설계 결정을 *왜* 했는지 짧게 적은 마크다운 페이지. *projection*(투영) = 한 방향 자동 파생(`pages/feedback/*.md` → `MEMORY.md` / `<learned_behaviors>`). *훅(hook)* = Claude Code가 라이프사이클 이벤트에서 자동으로 실행하는 스크립트. *hot.md* / *session-state.md* = "방금 무엇을 했는지"와 "다음에 무엇을 할지"를 담는 프로젝트별 캐시 파일 — 멈춘 프로젝트를 한 번에 이어 받을 수 있게 합니다. 전체 용어 풀이는 [용어 사전](#용어-사전) 참조.
+
+> **현재 자동화 범위와 다음 목표.** v1.2.0(현재)은 트리거 모델을 솔직하게 정리합니다. 위키 작업(자료 정리·검색·세션 마무리)은 여전히 사용자가 `/hypo:*` 명령어를 직접 입력해 시작합니다. 다만 **v1.1.0**부터 위키가 한 세션에서 얼마나 활용됐는지를 측정하는 *관측성 지표(observability score)* 가 들어갔고, **v1.2.0**은 그 위에 사용자가 시키지 않아도 자동으로 동작하는 영역 4개를 추가했습니다:
+> - **`feedback` 페이지를 단일 원천(source of truth)으로**(ADR 0031) — `pages/feedback/`에 한 번만 적으면, 위키가 `MEMORY.md`와 `~/.claude/CLAUDE.md`의 `<learned_behaviors>` 블록을 자동으로 갱신합니다.
+> - **확장 파일 동봉 동기화**(ADR 0024) — 위키 안의 `~/hypomnema/extensions/{agents,commands,hooks,skills}/`에 둔 파일을 자동으로 `~/.claude/`에 반영합니다. `--codex` 옵션을 추가하면 `hooks`·`commands`는 `~/.codex/`에도 반영되지만, `agents`와 `skills`는 Claude 전용이라 의도적으로 건너뜁니다.
+> - **프로젝트 자동 생성**(ADR 0023) — 작업 디렉터리를 git 저장소(`package.json`·`Cargo.toml` 등의 프로젝트 표식이 있는 곳)로 옮겼을 때 대응하는 위키 프로젝트가 없으면, 새로 만들지 물어봅니다.
+> - **세션 종료 자동 정리와 `/clear` 복구**(ADR 0022) — 의미 있는 세션이 끝날 때 "마무리 메모를 짧게 남길까요?"가 자동으로 뜨고, 마무리하지 않은 채 `/clear`를 입력해도 다음 세션 시작 시 이어서 정리할 수 있습니다.
+>
+> 스키마(`SCHEMA.md`)는 2.0으로 올라갑니다. `feedback` 페이지 타입에 9개의 필수 항목이 추가되며, `hypomnema upgrade --apply`를 실행하면 위키 루트에 `MIGRATION-v2.0.md`가 생성되어 단계별 보강 체크리스트를 제공합니다. 사용자가 직접 편집한 `SCHEMA.md`는 upgrade가 **덮어쓰지 않습니다** — 안내만 표시하고, 실제 반영은 사용자가 수동으로 결정합니다(이 정책을 코드에서는 *Option C*로 부릅니다).
 
 ---
 
@@ -70,9 +78,9 @@ hypomnema
 
 ## Hypomnema가 필요한 이유
 
-개인 지식 도구는 보통 네 가지 부류에 속하고, 각각 다른 지점에서 무너집니다:
+개인 지식 도구는 보통 다섯 가지 부류에 속하고, 각각 다른 지점에서 무너집니다:
 
-| | 통증 | 왜 복리가 안 되는가 |
+| | 어디서 막히는가 | 왜 지식이 쌓이지 않는가 |
 |---|---|---|
 | **노트 볼트** (마크다운 기반, 로컬 우선) | 수동 캡처, 수동 링크, 수동 재독 | 노트가 독립적으로 머무름. 합성 없음 |
 | **클라우드 지식 플랫폼** (페이지·DB 하이브리드) | 캡처는 빠르나 검색이 느림 | 키워드 기반 검색. LLM이 직접 접근 못 함 |
@@ -107,16 +115,45 @@ Hypomnema         ───►  합성 · 마크다운 · git · 훅 · 로컬
 | **포맷** | 평문 마크다운 + frontmatter | 마크다운 | 독자 포맷 | 벡터 스토어 | 독자 포맷 | HTML |
 | **백엔드** | 로컬 파일 + git | 로컬 파일 | SaaS | 서비스 / DB | SaaS | 서비스 |
 | **행동 튜닝** | `/hypo:feedback` → 영구 규칙 | 없음 | 없음 | 없음 | 일부 | 없음 |
-| **자율 동작(auto-behavior)** | 현재는 명시적 `/hypo:*` 트리거 기반; **v1.1에서 observability 점수 도입**, v2 목표 = 완전 자율 | 없음 | 없음 | 없음 | 블랙박스 | 없음 |
+| **자율 동작(auto-behavior)** | 명시적 `/hypo:*` 호출 + **v1.1 관측성 점수** + **v1.2 피드백 단일 원천 자동 반영 / 확장 파일 동봉 동기화 / 프로젝트 자동 생성 / 세션 종료 시 최소 마무리 자동 제안**; v2 목표는 완전 자율 동작 | 없음 | 없음 | 없음 | 블랙박스 | 없음 |
 | **셋업 비용** | 명령 1개 | 설치 1번 | 가입 | 파이프라인 구축 | 가입 | 레포 연결 |
 | **락인** | 0 (마크다운 + git) | 낮음 | 높음 | 중간 | 높음 | 중간 |
 
-### 이 트레이드오프가 가져오는 것
+### 이 선택이 가져다주는 것
+
+- **저장이 아니라 합성.** 끝까지 읽지도 못한 글들의 무덤이 쌓이지 않습니다. `/hypo:ingest`는 매번 구조화된 페이지를 만들고, 같은 주제의 다음 인제스트는 새 페이지가 아닌 *기존 페이지의 갱신*으로 들어갑니다.
+- **밀도가 복리로 자란다.** 소스 100개짜리 위키가 단절된 페이지 100개로 끝나면 의미가 없습니다. 실사용 3개월 시점이면 페이지 수는 소스 증가보다 천천히 늘고, 교차 링크는 오히려 더 빠르게 늘어납니다.
+- **맥락 전환이 0이다.** 어차피 Claude Code 안에서 일하는 중입니다. 위키는 슬래시 명령 한 줄로 닿습니다 — 새 탭도, 다른 앱도, 추가 로그인도 없습니다.
+- **저장 형식이 오래 살아남는다.** 평문 마크다운 + git 조합은 20년 뒤에도 읽힙니다. 오프라인에서도 `grep`이 됩니다. 언제든 다른 도구로 옮길 수 있고, 아직 세상에 없는 미래의 AI 도우미도 별도 변환 없이 그대로 읽을 수 있습니다.
+
+---
+
+## 용어 사전
 
-- **저장이 아닌 합성.** 다 못 읽은 글들의 무덤이 만들어지지 않습니다. `/hypo:ingest`가 매번 구조화된 페이지를 만들고, 같은 주제의 후속 인제스트는 그 페이지를 *갱신*합니다.
-- **복리적 밀도.** 100개의 소스를 모은 위키가 100개의 단절된 페이지가 되어선 안 됩니다. 실사용 3개월 시점에서 페이지 수는 sub-linear로 늘고 교차 링크는 super-linear로 늘어납니다.
-- **컨텍스트 전환 0.** 이미 Claude Code 안에 있습니다. 위키는 슬래시 명령 하나 떨어진 거리 — 새 탭도, 새 앱도, 새 로그인도 없습니다.
-- **미래 안전한 저장소.** 평문 마크다운 + git이라는 의미는 — 20년 뒤에도 읽을 수 있고, 오프라인에서도 grep 되며, 언제든 다른 도구로 옮겨갈 수 있고, 아직 만나지 않은 미래의 AI 어시스턴트도 그대로 이해할 수 있다는 뜻입니다.
+Hypomnema가 본문에서 반복적으로 쓰는 용어를 한 표로 모았습니다. 본문을 훑어볼 때 이 표를 옆 탭에 열어 두시면 됩니다.
+
+| 용어 | Hypomnema에서의 의미 |
+|---|---|
+| **프런트매터(frontmatter)** | 마크다운 페이지 맨 위의 YAML 블록 — `title`, `type`, `tags` 같은 항목이 들어갑니다 |
+| **위키링크(wikilink)** | `[[페이지-슬러그]]` 형태의 페이지 간 교차 참조 — `lint` 시 유효성이 확인됩니다 |
+| **ADR** | "Architecture Decision Record" — 자명하지 않은 설계 결정을 *왜* 했는지 짧게 기록하는 마크다운 페이지 |
+| **스키마(schema)** | `SCHEMA.md`에 정의된 타입 분류 + 필수 항목 규칙 — 페이지가 유효한지의 기준 |
+| **lint** | 읽기 전용 검증기(`hypomnema lint`) — 프런트매터·위키링크·스키마를 한꺼번에 점검 |
+| **projection(투영)** | 한 방향 자동 파생 — `pages/feedback/*.md` → `MEMORY.md`와 CLAUDE.md `<learned_behaviors>` |
+| **단일 원천(source of truth, SoT)** | 사용자가 편집하는 단 하나의 파일 — 단방향 반영(projection)은 그로부터만 파생되며, 역방향은 허용되지 않습니다 |
+| **훅(hook)** | Claude Code가 라이프사이클 이벤트(`SessionStart`, `Stop` 등)에 자동으로 실행하는 스크립트 |
+| **라이프사이클 이벤트** | Claude Code가 플러그인에 알리는 시점 — 세션 시작/프롬프트 제출/도구 사용/`compact` 요청/세션 종료 등 |
+| **`hot.md`** | 프로젝트별 캐시 — "방금 무엇을 했는지"(직전 세션의 핵심) |
+| **`session-state.md`** | 프로젝트별 캐시 — "다음에 무엇을 할지"(다음 세션 시작 시 주입되는 이어받기 데이터) |
+| **`.hypoignore`** | 모든 콘텐츠 주입 훅과 `ingest`에서 제외할 경로(글롭 패턴) |
+| **관측성 지표(observability score)** | 세션별 측정값(ingest·query·session-close·citation 비율) — 위키가 실제로 활용됐는지를 보여줍니다 |
+| **manifest** | 설치 스크립트가 작성하는 작은 JSON — 어떤 파일을 어떤 SHA로 설치했는지 정확히 기록 |
+| **`additionalContext`** | Claude Code 훅이 프롬프트에 컨텍스트를 끼워 넣는 필드 — 콘텐츠 주입 훅의 출력 위치 |
+| **바이트 동일(byte-equal)** | `--apply` 전후가 비트 단위로 같은 파일 — "건드리지 않았다"는 가장 강한 보장 |
+| **BM25** | 고전적인 전문(全文) 랭킹 알고리즘 — `/hypo:query`의 MISS 내성 검색을 담당 |
+| **Option C** | `hypomnema upgrade --apply`가 사용자의 `SCHEMA.md`를 절대 덮어쓰지 않는 정책 — 마이그레이션 보고서만 작성하고, 적용은 사용자가 수동으로 |
+
+본문에서 마주친 용어가 이 표에 빠져 있다면 문서 버그입니다. 이슈를 남겨 주세요.
 
 ---
 
@@ -132,7 +169,7 @@ RAG는 *낯선* 코퍼스에 강합니다 — 100만 페이지 법률 아카이
 - 사용자는 단편이 아니라 **관점**을 원합니다.
 - 청크 수는 캡처에 비례해 선형 증가합니다 — 지식이 늘지 않아도.
 
-Hypomnema는 청크가 아니라 페이지를 지식 단위로 다룹니다. 새 소스는 페이지에 대해 reconcile됩니다. 결과물은 위키 문서처럼 읽힙니다 — 정확히 위키 문서이기 때문입니다.
+Hypomnema는 청크가 아니라 페이지를 지식 단위로 다룹니다. 새 소스는 관련 페이지에 반영됩니다 — 기존 페이지가 있으면 갱신하고, 없으면 새 페이지로 만듭니다. 결과물은 위키 문서처럼 읽힙니다 — 정확히 위키 문서이기 때문입니다.
 
 ### 2. 왜 독자 포맷이 아니라 **마크다운 + git**인가
 
@@ -166,7 +203,7 @@ Hypomnema는 청크가 아니라 페이지를 지식 단위로 다룹니다. 새
 
 ### 7. 왜 privacy mode 플래그가 아니라 **`.hypoignore`** 인가
 
-v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실과 부딪히자마자 무너졌습니다 — 모든 privacy 결정은 결국 *경로 단위* 질문이었고, 그 질문은 단일 파일(`.hypoignore`)이 네이티브로 처리합니다. v1.1은 mode 개념을 통째로 삭제했습니다. 단일 파일, 단일 진실 소스.
+v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실과 부딪히자마자 무너졌습니다 — 모든 privacy 결정은 결국 *경로 단위* 질문이었고, 그 질문은 단일 파일(`.hypoignore`)이 네이티브로 처리합니다. v1.1은 mode 개념을 통째로 삭제했습니다. 한 파일이 모든 결정을 담는 단일 원천 구조입니다.
 
 ---
 
@@ -180,14 +217,14 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 |---|---|---|
 | `/hypo:ingest` | 원본을 `sources/`에 보관하고 Claude가 `pages/`에 구조화된 페이지를 합성. 셸 헬퍼(`scripts/ingest.mjs`)는 read-only — 아직 ingest되지 않은 소스를 *목록만* 출력 | 보관할 가치가 있는 글을 읽었을 때 |
 | `/hypo:query` | BM25 검색 + LLM 합성 + `[[wikilink]]` 인용 | 자기 노트에 근거한 답변이 필요할 때 |
-| `/hypo:crystallize` | 초안 합성 + 11단계 session-close 체크리스트 | 비자명한 세션 종료 시 |
-| `/hypo:resume` | 활성 프로젝트의 가장 최근 세션 상태 로드 | 일시 중단된 프로젝트로 돌아올 때 |
-| `/hypo:feedback` | AI 행동 교정 기록, 영구 규칙으로 승격 가능 | Claude가 잘못 하거나 정확히 잘 했을 때 |
-| `/hypo:verify` | `verify_by` frontmatter 페이지 감사 | 시간 제약 지식이 노후화됐을 가능성이 있을 때 |
+| `/hypo:crystallize` | 세션 마무리 체크리스트(1~6단계) 실행. 요청 시 초안 합성(7~11단계)까지 수행 | 단순하지 않은 세션을 마칠 때 |
+| `/hypo:resume` | 활성 프로젝트의 가장 최근 세션 상태를 불러오기 | 잠시 미뤄둔 프로젝트로 돌아올 때 |
+| `/hypo:feedback` | AI 행동 교정 사항을 기록. 영구 규칙으로 승격 후보가 됨 | Claude가 잘못한 순간 — 또는 반대로 정확히 잘한 순간 |
+| `/hypo:verify` | `verify_by` 프런트매터가 붙은 페이지를 점검 | 시간이 지나 옛 정보가 됐을 가능성이 있을 때 |
 | `/hypo:lint` | frontmatter, 위키링크, 스키마 검증 | 커밋 전, CI에서 |
 | `/hypo:graph` | 위키링크 의존성 그래프 생성 | 구조적 성장을 보고 싶을 때 |
 
-### 라이프사이클 훅 (10개)
+### 라이프사이클 훅 (14개)
 
 | 훅 | 이벤트 | 역할 |
 |---|---|---|
@@ -196,14 +233,22 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 | `hypo-lookup.mjs` | `UserPromptSubmit` | BM25 top-3 HIT 주입 / MISS → 가까운 슬러그 신호 |
 | `hypo-compact-guard.mjs` | `UserPromptSubmit` | `/compact` 감지 → session-close 체크리스트 강제 |
 | `hypo-cwd-change.mjs` | `CwdChanged` | cwd에 매칭되는 프로젝트 `hot.md` 주입 |
-| `hypo-file-watch.mjs` | `FileChanged` | 위키 파일 변경 알림 |
+| `hypo-file-watch.mjs` | `FileChanged` | 위키 파일 변경 알림 (`.hypoignore` 준수 — 매칭 경로는 LLM 컨텍스트로 재주입되지 않음) |
 | `hypo-auto-stage.mjs` | `PostToolUse(Write/Edit)` | 위키 파일 자동 stage |
 | `hypo-auto-commit.mjs` | `Stop` | 자동 commit + pull + push |
 | `hypo-hot-rebuild.mjs` | `Stop` | `hot.md` 재생성 |
 | `hypo-personal-check.mjs` | `PreCompact` | lint 실패 / session-close 미완 시 compact 차단 |
+| `hypo-session-end.mjs` | `SessionEnd` | SessionEnd 마커 기록 — 다음 SessionStart가 `source=clear` 복구를 감지하기 위함 (ADR 0022) |
+| `hypo-session-record.mjs` | `Stop` | observability 점수 + auto-resume 신호용 세션 메타데이터 기록 |
+| `hypo-auto-minimal-crystallize.mjs` | `Stop` | 단순하지 않은 세션이 끝났을 때 `/hypo:crystallize --apply-session-close --minimal`을 자동 제안 (사용자가 동의하면 실행, ADR 0022 Layer 3) |
+| `hypo-web-fetch-ingest.mjs` | `PostToolUse(WebFetch/WebSearch)` | WebFetch/WebSearch 완료 후 `additionalContext`에 `/hypo:ingest` 권유 안내 주입 (privacy 보호: WebFetch URL의 query/hash/userinfo 제거) |
 
 모든 훅은 위키 루트를 `HYPO_DIR` 환경변수 → `hypo-config.md` 스캔 → `~/hypomnema` 기본값 순으로 해결하며, `hypo-shared.mjs`(`hooks.json`의 `shared` 필드로 선언)를 공유합니다.
 
+이와 별도로 `SessionStart` 훅은 npm 레지스트리와 Claude Code 플러그인 마켓플레이스를 백그라운드에서 확인합니다(세션 시작을 막지 않습니다). 새 버전이 게시되어 있으면 다음 세션 시작 시 "Update available!" 안내가 한 줄 표시됩니다. `HYPO_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`을 지정하거나 `CI=true` 환경에서 실행하면 점검을 건너뜁니다.
+
+위 네 가지 레인 외의 v1.2 세부 수정 — 오래된 `design-history.md`를 잡는 `W8` lint, 프로젝트 간 누출을 막는 `project:*` 정확 일치 필터(PR #59), 코드 주석 정리 1단계(PR #58) — 는 [`CHANGELOG.md`](CHANGELOG.md)를 참고하세요.
+
 ### 셋업 & 유지보수
 
 | 명령어 | 목적 |
@@ -213,17 +258,18 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 | `/hypo:upgrade` | 훅/설정을 최신 버전으로 마이그레이션 |
 | `/hypo:uninstall` | 훅 및 등록 정보 제거 |
 | `/hypo:stats` | 위키 통계 |
+| `/hypo:audit` | observability 감사 (세션별 메트릭, 주간 보고서) |
 
 ### Claude Agent Skills
 
-합성이 핵심인 명령어(`ingest`, `query`, `crystallize`, `lint`, `verify`, `graph`)는 `skills/<name>/SKILL.md`로도 등록되어 있어, 대화가 해당 description에 매칭되면 **Claude Agent Skills**로 자동 트리거됩니다 — 슬래시 명령 없이도.
+합성이 핵심인 명령어(`ingest`, `query`, `crystallize`, `lint`, `verify`, `graph`)는 `skills/<name>/SKILL.md`로도 등록되어 있습니다. 대화 내용이 해당 스킬의 설명(`description`)과 맞아떨어지면 **Claude Agent Skills** 메커니즘이 슬래시 명령 입력 없이도 자동으로 호출합니다.
 
 ---
 
 ## 시나리오
 
 **A — 새 기술 학습.**
-Kubernetes 문서와 블로그 글을 읽는 중. 각 URL을 `/hypo:ingest`에 넣습니다. 세 번째 글에서 Claude가 새 페이지 대신 기존 `kubernetes-networking.md`를 갱신하기 시작합니다. 일주일 후 `/hypo:query "pod CIDR 할당은 어떻게 동작하나요?"`는 자신의 노트를 인용한 합성 답변을 돌려줍니다.
+Kubernetes 문서와 블로그 글을 읽는 중입니다. 각 URL을 `/hypo:ingest`에 넘깁니다. 세 번째 글쯤 되면 Claude가 새 페이지를 만드는 대신 기존 `kubernetes-networking.md`를 갱신하기 시작합니다. 일주일 뒤 `/hypo:query "pod CIDR 할당은 어떻게 동작하나요?"`를 실행하면, 본인이 직접 정리해 둔 노트를 인용한 합성 답변이 돌아옵니다.
 
 **B — 엔지니어링 결정 추적.**
 중요한 변경 사항을 머지하기 전에 설계 문서나 PR 설명을 `/hypo:ingest`로 처리합니다. Claude가 컨텍스트, 트레이드오프, 결정 사항이 담긴 ADR 스타일 페이지를 작성합니다. 이후 `[[wikilink]]` 참조가 관련 프롬프트에 근거를 직접 주입합니다.
@@ -232,7 +278,7 @@ Kubernetes 문서와 블로그 글을 읽는 중. 각 URL을 `/hypo:ingest`에
 몇 주에 걸쳐 한 주제의 논문들을 읽습니다. 각 `/hypo:ingest`가 논문을 합성하고 기존 페이지와 교차 연결합니다. 언제든 `/hypo:query`로 자신의 노트에 근거한 문헌 리뷰 스타일 요약을 받을 수 있습니다.
 
 **D — AI 행동 튜닝.**
-Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실행합니다. 교정 사항이 `pages/feedback/`에 저장되고 세션 시작 시 주입되어, 같은 실수가 반복되지 않습니다 — 한 대화 안이 아니라 세션 간에 걸쳐서요.
+Claude가 잘못한 순간 — 또는 반대로 정확히 잘한 순간 — `/hypo:feedback`을 실행합니다. 교정 내용이 `pages/feedback/`에 저장되고 다음 세션 시작 시 자동으로 주입되므로, 같은 실수가 다시 반복되지 않습니다. 한 번의 대화 안에서만 효력이 있는 게 아니라, 세션이 바뀌어도 그대로 유지된다는 뜻입니다.
 
 **E — 일시 중단된 프로젝트 재개.**
 3주 동안 손 놓았던 프로젝트로 돌아옵니다. 다음 세션 시작 시 `hypo-session-start.mjs`가 `projects/<name>/session-state.md`를 읽고 "다음 작업"과 최근 결정 사항을 컨텍스트에 주입합니다. 첫 프롬프트를 입력하기 전에 이미 업무 파악이 끝나 있습니다.
@@ -296,15 +342,17 @@ Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실
 
 위키 루트에 `hypo-config.md`를 두면 환경변수 없이도 기기 간 이식이 가능합니다.
 
-`.hypoignore`는 훅이 무시할 경로를 정의합니다 (기본: `*.pdf`, `*.zip`, `*.pem`, `*.env` 등). 직접 편집하면 됩니다 — privacy mode 플래그는 없습니다. 단일 파일, 단일 진실 소스.
+`.hypoignore`는 훅이 무시할 경로를 정의합니다 (기본: `*.pdf`, `*.zip`, `*.pem`, `*.env` 등). 직접 편집하면 됩니다 — privacy mode 플래그는 없습니다. 파일 하나가 모든 결정을 담는 단일 원천 구조입니다.
+
+> **모델 사업자에게 전송되는 범위 안내.** Hypomnema 훅은 위키 본문을 Claude Code의 추가 컨텍스트(`additionalContext`)에 실어 보내며, 이 내용은 프롬프트의 일부로 Claude 모델 사업자에게 전송됩니다. 따라서 `.hypoignore`에 등록된 경로는 모든 주입 훅(`hypo-file-watch`, `hypo-session-start`, `hypo-cwd-change`, `hypo-lookup`)과 `ingest`에서 제외되지만, 등록되지 *않은* 파일은 전송 대상이 됩니다. (`hypo-auto-stage`/`hypo-auto-commit`은 git 스테이징용 훅이라 컨텍스트를 주입하지는 않지만, 스테이징 판단에도 동일하게 `.hypoignore`를 참고합니다.) 비밀 정보는 위키에 두지 마시고, `HYPO_DIR` 아래에 민감한 내용을 저장하기 전에 `.hypoignore` 패턴을 먼저 점검하시기 바랍니다.
 
-> **git sync 범위.** Hypomnema는 `~/hypomnema/` 위키 자체만 git sync합니다. Claude Code 설정(`~/.claude/`)은 의도적으로 Hypomnema가 **관리하지 않습니다** — agent·skill·settings의 기기 간 동기화는 [chezmoi](https://www.chezmoi.io/) 같은 별도 dotfiles 매니저 사용을 권장합니다.
+> **git sync 범위.** Hypomnema는 `~/hypomnema/` 위키 자체만 git sync합니다. 단, `init` / `upgrade`는 `~/.claude/` 내부의 관리 대상 영역 — Hypomnema 자체 hook(`~/.claude/hooks/`), 슬래시 커맨드(`~/.claude/commands/hypo/`), `settings.json` 등록 — 을 설치·SHA 추적하며, v1.2.0 **extensions companion sync**(ADR 0024)에 의해 위키의 `~/hypomnema/extensions/`에 둔 `agents/`·`commands/`·`hooks/`·`skills/`도 자동 미러링합니다(`--codex` 옵션 시 `hooks`·`commands` 부분 집합만 `~/.codex/`로). 이 관리 대상 영역 *바깥*의 `~/.claude/` 콘텐츠는 의도적으로 Hypomnema가 **관리하지 않습니다** — 위키를 거치지 않는 기타 agent/skill, 머신 고유 `settings.local.json` 등 일반적인 Claude Code 설정 기기 간 동기화는 [chezmoi](https://www.chezmoi.io/) 같은 별도 dotfiles 매니저 사용을 권장합니다.
 
 ### `/hypo:*` 커맨드는 어디서 오는가?
 
 | 설치 경로 | 슬래시 커맨드 위치 |
 |---|---|
-| 플러그인 (Path A) | Claude Code 플러그인 캐시; `/plugin update`로 갱신 |
+| 플러그인 (Path A) | Claude Code 플러그인 캐시; `/plugin marketplace update hypomnema` 후 `/reload-plugins`로 갱신 |
 | npm CLI (Path B) | `~/.claude/commands/hypo/`; `hypomnema upgrade --apply`로 갱신, 파일별 SHA 추적. 사용자 수정본까지 덮어쓰려면 `--force-commands`(원본은 `.bak`으로 보존) |
 
 ---
@@ -320,7 +368,7 @@ Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실
 
 ## 상태
 
-- **테스트:** `npm test` 참조 — lane이 ship될 때마다 카운트가 변하므로 러너가 단일 진실 공급원
+- **테스트:** `npm test` 참조 — 레인이 ship될 때마다 카운트가 변하므로 러너가 단일 원천입니다
 - **CI:** 7개 독립 job (test matrix, lint, init/upgrade snapshots, replay, hypo-absent, uninstall-smoke)
 - **릴리스:** `v*` 태그 push 시 `npm publish --provenance` 자동 실행
 

package/README.md

@@ -19,9 +19,17 @@ _Make Claude take notes — and measure whether it actually does._
 
 [Quick Start](#quick-start) • [How It Compares](#how-it-compares) • [Design Decisions](#design-decisions) • [Features](#features) • [Architecture](docs/ARCHITECTURE.md) • [Contributing](docs/CONTRIBUTING.md)
 
-> Inspired by Andrej Karpathy's "LLM-native wiki" sketch and shaped by ten months of personal use, Hypomnema ships the full lifecycle — capture, synthesis, retrieval, session-resume — as Claude Code commands and lifecycle hooks.
+> Inspired by Andrej Karpathy's "LLM-native wiki" sketch and shaped by ten months of personal AI-workflow experiments plus one month of Hypomnema dogfooding before the v1.2.0 public release, Hypomnema ships the full lifecycle — capture, synthesis, retrieval, session-resume — as Claude Code commands and lifecycle hooks.
 
-> **Current state vs. v2 vision.** v1.0.1 (today) is honest about its trigger model: most wiki behavior — ingest, query, session-close — fires on **explicit `/hypo:*` commands**, with a handful of hooks providing auto-staging, session-state injection, and lookup signals. The v2 thesis is *fully autonomous* — Claude reading, writing, and synthesizing the wiki without being asked. **v1.1.0** is the first step on that ramp: instead of claiming auto-behavior, it ships an **observability score** that measures how often the wiki is actually used per session (ingest count, query count, session-close rate, citation rate) so you can see the auto-vs-manual ratio with your own eyes before the v2 work lands.
+> **Quick decoder for terms used below.** *frontmatter* = the YAML block at the top of a markdown file; *wikilink* = a `[[page-slug]]` cross-reference; *ADR* = "Architecture Decision Record", a short markdown page that records *why* a design choice was made; *projection* = a one-way derive (`pages/feedback/*.md` → `MEMORY.md` / `<learned_behaviors>`); *hook* = a script that Claude Code runs automatically on lifecycle events; *hot.md* / *session-state.md* = the per-project cache files that hold "what just happened" and "what's next" so a paused project resumes in one read. Full glossary lives under [Term decoder](#term-decoder).
+
+> **Current state vs. v2 vision.** v1.2.0 (today) is honest about its trigger model: most wiki behavior — ingest, query, session-close — still fires on **explicit `/hypo:*` commands**, but the auto-behavior surface is growing. The v2 thesis is *fully autonomous* — Claude reading, writing, and synthesizing the wiki without being asked. **v1.1.0** shipped the **observability score** that measures how often the wiki is actually used per session (ingest / query / session-close / citation rates). **v1.2.0** adds four load-bearing autonomous lanes on top:
+> - **feedback-as-SoT with one-way projections** — `pages/feedback/` becomes the single source-of-truth (SoT) for behavior corrections; the wiki one-way derives `MEMORY.md` and the `<learned_behaviors>` block inside `~/.claude/CLAUDE.md`, so you edit one place and the projections refresh on their own (ADR 0031 — full design rationale lives in `projects/hypomnema/decisions/0031-*.md` inside your wiki).
+> - **extensions companion sync** — anything you drop under `~/hypomnema/extensions/{agents,commands,hooks,skills}/` is mirrored into `~/.claude/` automatically; the optional `--codex` flag additionally mirrors `hooks` and `commands` into `~/.codex/` (agents/skills are Claude-only and skipped on the Codex target by design) (ADR 0024).
+> - **auto-project creation on cwd match** — when you `cd` into a git repo with a project marker (`package.json`, `Cargo.toml`, etc.) and no matching wiki project exists, Hypomnema offers to scaffold one for you (ADR 0023).
+> - **Stop-chain auto-minimal-crystallize + `/clear` recovery** — non-trivial sessions get an automatic "save a minimal session-close note?" prompt; `/clear` after a forgotten close is detected and recovered cleanly (ADR 0022).
+>
+> The schema (`SCHEMA.md`) bumps to 2.0 — the `feedback` page type now requires 9 mandatory frontmatter fields. `hypomnema upgrade --apply` writes `MIGRATION-v2.0.md` into the wiki root with a step-by-step backfill checklist. Your own `SCHEMA.md` is **never overwritten** by upgrade — we call this policy *Option C*: the upgrade only tells you what changed, and you apply the diff yourself.
 
 ---
 
@@ -70,7 +78,7 @@ Hooks handle the rest — auto-staging, auto-commit/push, session-state injectio
 
 ## Why Hypomnema
 
-Personal knowledge tools fall into four buckets, and each one breaks at a different place:
+Personal knowledge tools fall into five buckets, and each one breaks at a different place:
 
 | | Pain | Why it doesn't compound |
 |---|---|---|
@@ -107,7 +115,7 @@ Hypomnema          ───►  synthesis · markdown · git · hooks · local
 | **Format** | Plain markdown + frontmatter | Markdown | Proprietary | Vector store | Proprietary | HTML |
 | **Backend** | Local file + git | Local file | SaaS | Service / DB | SaaS | Service |
 | **Behavior tuning** | `/hypo:feedback` → permanent rules | None | None | None | Sometimes | None |
-| **Auto-behavior** | Explicit `/hypo:*` triggers today; **v1.1 ships an observability score**, v2 target = fully autonomous | None | None | None | Black box | None |
+| **Auto-behavior** | Explicit `/hypo:*` triggers + **v1.1 observability score** + **v1.2 feedback-as-SoT projection / extensions companion sync / auto-project / Stop-chain auto-minimal-crystallize**; v2 target = fully autonomous | None | None | None | Black box | None |
 | **Setup cost** | One command | One install | Sign-up | Pipeline build | Sign-up | Repo connect |
 | **Lock-in** | Zero (markdown + git) | Low | High | Medium | High | Medium |
 
@@ -120,6 +128,35 @@ Hypomnema          ───►  synthesis · markdown · git · hooks · local
 
 ---
 
+## Term decoder
+
+Hypomnema borrows vocabulary from a few worlds. These are the recurring terms used in the rest of the README — keep this table open in another tab while you skim.
+
+| Term | Meaning in Hypomnema |
+|---|---|
+| **frontmatter** | The YAML block at the top of a markdown page — `title`, `type`, `tags`, etc. |
+| **wikilink** | A `[[page-slug]]` cross-reference between pages; resolved at lint time |
+| **ADR** | "Architecture Decision Record" — a short markdown page recording *why* a non-obvious design choice was made |
+| **schema** | The type taxonomy + required-field rules in `SCHEMA.md` — what makes a page valid |
+| **lint** | A read-only validator (`hypomnema lint`) that checks frontmatter, wikilinks, and schema |
+| **projection** | A one-way automatic derivation — `pages/feedback/*.md` → `MEMORY.md` and CLAUDE.md `<learned_behaviors>` |
+| **SoT** ("source of truth") | The single file you edit; projections derive from it, never the other way around |
+| **hook** | A script Claude Code runs automatically on a lifecycle event (e.g. `SessionStart`, `Stop`) |
+| **lifecycle event** | A point Claude Code surfaces to plugins: session opens, prompt submitted, tool used, compact requested, session ends, etc. |
+| **`hot.md`** | Per-project cache: "what just happened" (most recent session highlights) |
+| **`session-state.md`** | Per-project cache: "what's next" (the resume payload for the next session) |
+| **`.hypoignore`** | Glob patterns that exclude paths from every content-injection hook and from `ingest` |
+| **observability score** | A per-session metric (ingest / query / session-close / citation rates) that measures whether the wiki is actually being used |
+| **manifest** | A small JSON the install scripts write to track exactly which files were installed and at what SHA |
+| **`additionalContext`** | The Claude Code hook field that injects extra context into the prompt — what content-injection hooks emit into |
+| **byte-equal** | A file that comes out of `--apply` bit-for-bit identical to before — the strongest "we did not touch this" guarantee |
+| **BM25** | A classic full-text ranking algorithm; powers the `/hypo:query` MISS-resistant lookup |
+| **Option C** | The policy that `hypomnema upgrade --apply` never overwrites your `SCHEMA.md` — it only writes a migration report you apply by hand |
+
+If a term you hit later in the README is missing here, that is a documentation bug — please open an issue.
+
+---
+
 ## Design Decisions
 
 Why each choice looks the way it does:
@@ -180,14 +217,14 @@ Eight commands cover the full capture → retrieval → consolidation cycle.
 |---|---|---|
 | `/hypo:ingest` | Saves the raw source under `sources/`; Claude synthesizes a structured page under `pages/`. The shell helper (`scripts/ingest.mjs`) is read-only — it only *lists* pending sources so you know what still needs ingesting | Anytime you read something worth keeping |
 | `/hypo:query` | BM25 retrieval + LLM synthesis with `[[wikilink]]` citations | When you need an answer grounded in your own notes |
-| `/hypo:crystallize` | Synthesizes drafts and runs the 11-step session-close checklist | End of a non-trivial session |
+| `/hypo:crystallize` | Runs the session-close checklist (steps 1~6) and, on request, synthesizes drafts (steps 7~11) | End of a non-trivial session |
 | `/hypo:resume` | Loads the most recent session state for an active project | Coming back to a paused project |
 | `/hypo:feedback` | Records an AI behavior correction; eligible for promotion to permanent rules | Right when Claude does something wrong (or exactly right) |
 | `/hypo:verify` | Audits pages with `verify_by` frontmatter | When time-bound knowledge might have aged out |
 | `/hypo:lint` | Validates frontmatter, wikilinks, schema | Before commits, in CI |
 | `/hypo:graph` | Generates a wikilink dependency graph | When you want to see structural growth |
 
-### Lifecycle hooks (10)
+### Lifecycle hooks (14)
 
 | Hook | Event | Role |
 |---|---|---|
@@ -196,14 +233,22 @@ Eight commands cover the full capture → retrieval → consolidation cycle.
 | `hypo-lookup.mjs` | `UserPromptSubmit` | BM25 top-3 HIT inject / MISS → closest-slug signal |
 | `hypo-compact-guard.mjs` | `UserPromptSubmit` | Detect `/compact` → enforce session-close checklist |
 | `hypo-cwd-change.mjs` | `CwdChanged` | Inject the matching project's `hot.md` |
-| `hypo-file-watch.mjs` | `FileChanged` | Notify on wiki-file changes |
+| `hypo-file-watch.mjs` | `FileChanged` | Notify on wiki-file changes (honors `.hypoignore` — matched paths are never re-emitted into LLM context) |
 | `hypo-auto-stage.mjs` | `PostToolUse(Write/Edit)` | Auto-stage wiki-file edits |
 | `hypo-auto-commit.mjs` | `Stop` | Auto commit + pull + push |
 | `hypo-hot-rebuild.mjs` | `Stop` | Rebuild `hot.md` |
 | `hypo-personal-check.mjs` | `PreCompact` | Block compact on lint failures or unfinished session-close |
+| `hypo-session-end.mjs` | `SessionEnd` | Write a SessionEnd marker so SessionStart can detect `source=clear` recovery (ADR 0022) |
+| `hypo-session-record.mjs` | `Stop` | Record session metadata for the observability score and auto-resume signaling |
+| `hypo-auto-minimal-crystallize.mjs` | `Stop` | Offer (and on consent run) `/hypo:crystallize --apply-session-close --minimal` after non-trivial sessions (ADR 0022 Layer 3) |
+| `hypo-web-fetch-ingest.mjs` | `PostToolUse(WebFetch/WebSearch)` | Inject a `/hypo:ingest` nudge into `additionalContext` after a URL resolution (privacy-aware: redacts query/hash/userinfo) |
 
 All hooks resolve the wiki root via `HYPO_DIR` env → `hypo-config.md` scan → `~/hypomnema` default, and share `hypo-shared.mjs` (declared via `hooks.json`'s `shared` field).
 
+Additionally, the `SessionStart` hook performs a non-blocking background check against npm and the Claude Code plugin marketplace and prints an "Update available!" banner the next time a newer Hypomnema version has been published. Opt out with `HYPO_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`, or by running under `CI=true`.
+
+For fix-level v1.2 detail beyond the lanes above — `W8` stale `design-history.md` lint, exact-match `project:*` filter for cross-project feedback projection (PR #59), and the comment-hygiene Phase 1 cleanup (PR #58) — see [`CHANGELOG.md`](CHANGELOG.md).
+
 ### Setup & maintenance
 
 | Command | Purpose |
@@ -213,6 +258,7 @@ All hooks resolve the wiki root via `HYPO_DIR` env → `hypo-config.md` scan →
 | `/hypo:upgrade` | Migrate hooks/config to the latest version |
 | `/hypo:uninstall` | Remove hooks and registrations |
 | `/hypo:stats` | Wiki statistics |
+| `/hypo:audit` | Observability audit (per-session metrics, weekly report) |
 
 ### Claude Agent Skills
 
@@ -298,13 +344,15 @@ Place a `hypo-config.md` at the wiki root to make it portable across machines wi
 
 `.hypoignore` controls which paths the hooks ignore (default: `*.pdf`, `*.zip`, `*.pem`, `*.env`, …). Edit it directly — there is no privacy mode flag; one file, one source of truth.
 
-> **Scope of git sync.** Hypomnema git-syncs only the `~/hypomnema/` wiki itself. Your Claude Code configuration (`~/.claude/`) is intentionally **not** managed by Hypomnema — for cross-machine sync of agents, skills, and settings, the recommended pattern is a separate dotfiles manager such as [chezmoi](https://www.chezmoi.io/).
+> **Provider transmission disclaimer.** Hypomnema hooks emit wiki content into Claude Code's `additionalContext`, which is transmitted to the Claude model provider as part of the prompt. `.hypoignore` is enforced at every content-injection hook (`hypo-file-watch`, `hypo-session-start`, `hypo-cwd-change`, `hypo-lookup`) and at `ingest`, but any file *not* matched by `.hypoignore` is fair game for transmission. (`hypo-auto-stage` and `hypo-auto-commit` are git-staging hooks, not injection points, and also honor `.hypoignore` for their staging decisions.) Keep secrets out of the wiki, and review `.hypoignore` patterns before storing anything sensitive under `HYPO_DIR`.
+
+> **Scope of git sync.** Hypomnema git-syncs only the `~/hypomnema/` wiki itself. `init` / `upgrade` actively install and SHA-track a defined surface inside `~/.claude/` — Hypomnema's own hooks (`~/.claude/hooks/`), slash commands (`~/.claude/commands/hypo/`), and `settings.json` registrations — plus, via v1.2.0 **extensions companion sync** (ADR 0024), any `agents/` · `commands/` · `hooks/` · `skills/` you ship inside `~/hypomnema/extensions/` (and with `--codex`, the `hooks` + `commands` subset into `~/.codex/`). Anything *outside* that defined surface in `~/.claude/` is intentionally **not** managed by Hypomnema — for general cross-machine sync of Claude Code configuration (other agents/skills not staged via the wiki, machine-specific `settings.local.json`, etc.), the recommended pattern is still a separate dotfiles manager such as [chezmoi](https://www.chezmoi.io/).
 
 ### Where do `/hypo:*` commands live?
 
 | Install path | Slash commands served from |
 |---|---|
-| Plugin (Path A) | Claude Code's plugin cache; updated via `/plugin update` |
+| Plugin (Path A) | Claude Code's plugin cache; updated via `/plugin marketplace update hypomnema` then `/reload-plugins` |
 | npm CLI (Path B) | `~/.claude/commands/hypo/`; updated via `hypomnema upgrade --apply` with per-file SHA tracking. Pass `--force-commands` to overwrite hand-edits (creates `.bak`). |
 
 ---

package/commands/audit.md

@@ -28,9 +28,9 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
   ```bash
   node <package-root>/scripts/session-audit.mjs [--hypo-dir="<path>"] [--limit=20]
   ```
-- **Weekly report (when the user asks for "weekly", "score", or names a week)** — write the report to `pages/observability/<YYYY-WW>.md`:
+- **Weekly report (when the user asks for "weekly", "score", or names a week)** — write the report to `journal/weekly/<YYYY-Www>.md` (spec §6.4 SoT):
   ```bash
-  node <package-root>/scripts/weekly-report.mjs [--hypo-dir="<path>"] [--week=YYYY-WW] --write
+  node <package-root>/scripts/weekly-report.mjs [--hypo-dir="<path>"] [--week=YYYY-Www] --write
   ```
 - **JSON for tooling** — append `--json` to either script.
 

package/commands/crystallize.md

@@ -4,47 +4,125 @@ description: Crystallize draft notes into stable knowledge — also the session-
 
 You are running `/hypo:crystallize`. This command serves two purposes:
 
-1. **Session close** — if invoked at the end of a session, run the session-close checklist first
+1. **Session close** — if invoked at the end of a session, run the session-close mechanical-apply path
 2. **Knowledge synthesis** — consolidate draft or scattered wiki pages into stable, well-linked pages
 
 ---
 
 ## Step 1 — Detect context
 
-If the user invoked `/hypo:crystallize` to close a session (phrases like "세션 종료", "오늘 작업 마무리", "session close", or "wrap up"), run Steps 2–3 (session-close checklist) **before** the synthesis scan. Otherwise skip to Step 4.
+If the user invoked `/hypo:crystallize` to close a session (phrases like "세션 종료", "오늘 작업 마무리", "session close", or "wrap up"), run Steps 2–4 (session-close mechanical apply + recovery) **before** the synthesis scan. Otherwise skip to Step 5.
 
 ---
 
-## Step 2 — Session-close checklist
+## Step 2 — Compose the session-close payload
 
-Work through each item in order. For an explicit session-close invocation, proceed automatically without asking for confirmation on each item.
+The session-close path is **payload-driven** (fix #38). Instead of writing the 5 mandatory files one-by-one, you compose a single JSON payload that describes the full session-close state, then hand it to `crystallize.mjs --apply-session-close`, which performs idempotent atomic writes and gates the result with lint.
 
-1. **session-state.md** — update `projects/<name>/session-state.md` with the next tasks list for the upcoming session (what to tackle first next time).
-2. **hot.md (project)** — update `projects/<name>/hot.md` with a session snapshot: what changed and decisions made. Keep under 500 words. Do not put next-step tasks here; those belong in session-state.md.
-3. **hot.md (root)** — update `<hypo-root>/hot.md` active-projects pointer table: set the `Last Session` date for this project to today.
-4. **session-log** — append a session entry to `projects/<name>/session-log/YYYY-MM.md` (create the file if it does not exist for this month).
-5. **open-questions** — only if `pages/open-questions.md` exists and questions were raised or resolved this session: move resolved ones out; add newly raised ones. Skip if unchanged.
-6. **log.md** — append a `session` entry to `<hypo-root>/log.md`.
+Payload shape (5 required + 1 conditional, per Spec §5.2.7 / §8.3 + ADR 0029):
+
+```json
+{
+  "project": "<project-name>",
+  "date": "YYYY-MM-DD",
+  "sessionState": { "content": "<full body of projects/<name>/session-state.md>" },
+  "projectHot": { "content": "<full body of projects/<name>/hot.md>" },
+  "rootHot": { "content": "<full body of <hypo-root>/hot.md>" },
+  "sessionLog": { "entry": "<entry to append to projects/<name>/session-log/YYYY-MM.md>" },
+  "log": { "entry": "<entry to append to <hypo-root>/log.md>" },
+  "openQuestions": { "content": "<full body of pages/open-questions.md>" }
+}
+```
+
+> **Important:** the JSON above is a literal template — do not add `//` or `#` comments when materializing it. `readPayload()` runs `JSON.parse`, which rejects comments and would fail the apply before any write.
+
+Field rules:
+
+- `project` — optional. Falls back to the active project from root `hot.md` pointer table.
+- `date` — optional. Defaults to today (local). Must be `YYYY-MM-DD` if supplied.
+- `openQuestions` — optional. Include only when `pages/open-questions.md` exists and changed this session.
+- All other top-level fields are required.
+
+Notes:
+
+- `sessionState` / `projectHot` / `rootHot` / `openQuestions` are **overwrite** (full-file content). `sessionLog` / `log` are **append** (entry-level idempotency — exact-entry dedup, safe to re-run).
+- Frontmatter `updated:` is NOT auto-fixed. If your payload's `updated:` is stale, the post-apply verification gate will fail with `stage='post-apply-verification'` and you must fix the payload and retry.
+- Write the payload to a temp path, e.g. `/tmp/hypo-session-close-<YYYY-MM-DD>.json`.
+
+Content guidance for each slot:
+
+1. **sessionState** — next tasks list for the upcoming session (what to tackle first next time).
+2. **projectHot** — session snapshot under 500 words: what changed and decisions made. Do **not** put next-step tasks here; those belong in `sessionState`.
+3. **rootHot** — active-projects pointer table with this project's `Last Session` date set to today.
+4. **sessionLog** — one session entry to append to `projects/<name>/session-log/YYYY-MM.md`.
+5. **log** — one `session` entry to append to `<hypo-root>/log.md`.
+6. **openQuestions** (conditional) — only if `pages/open-questions.md` exists and questions were raised or resolved this session.
+
+---
+
+## Step 3 — Apply the payload
+
+```bash
+node <package-root>/scripts/crystallize.mjs \
+  --apply-session-close \
+  --payload=/tmp/hypo-session-close-<YYYY-MM-DD>.json \
+  --session-id=<current-session-id> \
+  --hypo-dir="<path>" \
+  --json
+```
+
+**`--session-id` (fix #27 PR-C):** pass the current session's id whenever you
+know it — most importantly when this close was triggered by a `[WIKI_AUTOCLOSE]`
+Stop-hook block (the block reason prints the exact `--session-id` to use). On a
+verified close (`ok: true` + clean git tree), it writes the per-session marker
+`HYPO_DIR/.cache/session-closed-<id>.marker`. That marker is what tells the
+Stop-chain Layer 3 hook (`hypo-auto-minimal-crystallize`) the session is closed,
+so it stops re-prompting. Omit it only when running crystallize purely for
+synthesis (no session-close intent) — the marker is then simply not written.
+
+**Behavior (fix #39 option D + fix #40 lint gates):**
+
+| Invocation | Behavior |
+|---|---|
+| `--apply-session-close` (no `--payload`) | **Probe mode** — exits 0 with "오늘 이미 close 완료로 보임" if all 5 files are fresh today; exits 1 with "payload is required" otherwise. Cheap "already complete?" check. |
+| `--apply-session-close --payload=<path>` | **Always-apply** — payload presence = explicit close intent. Per-field idempotent writes (no-op when bytes match), then strict verification + lint gate. Safe to re-run. |
+| `--apply-session-close --payload=<path> --session-id=<id>` | Same as above, **plus** writes the per-session closed marker on success (clean git required). The Stop-chain Layer 3 path. |
+| `--apply-session-close --force` | Skips the probe early-exit. `--payload` still required for any actual apply work. |
+
+**Two lint gates run automatically (fix #40):**
+
+1. **Preflight** — `lint.mjs --json` runs **before** any payload bytes are written. Errors in files this payload will overwrite (sessionState / projectHot / rootHot / openQuestions) are filtered (they're about to be replaced anyway). Errors in any other file → exit 1 with `stage='preflight-lint'`, no apply occurs.
+2. **Post-apply** — lint re-runs after the writes. Catches payloads that introduce a broken wikilink or malformed body. Surfaces as `stage='post-apply-lint'` (or `'post-apply-verification+lint'` if the freshness gate also fails).
 
 ---
 
-## Step 3 — Session-close confirmation
+## Step 4 — Stage-based recovery
+
+The result JSON includes a `stage` field when `ok: false`. Branch on it:
 
-After completing the checklist, report:
+| `stage` | What broke | How to recover |
+|---|---|---|
+| `preflight-lint` | A non-payload file in the wiki has a blocking lint error. | Fix the lint error in that file (separate from session-close), then re-run. No payload bytes were written. |
+| `post-apply-verification` | A mandatory file's `updated:` frontmatter is stale (≠ today) after apply. | Edit the payload's stale `content` (or supply correct `date`), then re-run. Writes are idempotent — re-applying a corrected payload is safe. |
+| `post-apply-lint` | The payload itself introduced a lint blocker (broken wikilink, bad frontmatter). | Fix the offending content in the payload, then re-run. |
+| `post-apply-verification+lint` | Both above. | Fix both; re-run. |
 
-- ✓ session-state.md updated
-- ✓ hot.md (project + root) updated
+Once `ok: true`, report:
+
+- ✓ session-state.md applied
+- ✓ hot.md (project + root) applied
 - ✓ session-log entry appended
-- ✓ open-questions updated (or skipped if unchanged)
-- ✓ log.md updated
+- ✓ open-questions applied (or skipped if unchanged)
+- ✓ log.md entry appended
+- ✓ post-apply lint clean
 
 Then ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
 
-If the user says stop, end here. Otherwise continue to Step 4.
+If the user says stop, end here. Otherwise continue to Step 5.
 
 ---
 
-## Step 4 — Surface synthesis candidates
+## Step 5 — Surface synthesis candidates
 
 Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
 
@@ -56,7 +134,7 @@ Show the output to the user. If no candidates are found, tell them Hypomnema loo
 
 ---
 
-## Step 5 — Choose what to crystallize
+## Step 6 — Choose what to crystallize
 
 If candidates exist, ask:
 
@@ -67,7 +145,7 @@ If candidates exist, ask:
 
 ---
 
-## Step 5a — Tag cluster synthesis
+## Step 6a — Tag cluster synthesis
 
 For a tag cluster:
 
@@ -89,7 +167,7 @@ For a tag cluster:
 
 ---
 
-## Step 5b — Draft upgrade
+## Step 6b — Draft upgrade
 
 For a draft page:
 
@@ -100,7 +178,7 @@ For a draft page:
 
 ---
 
-## Step 5c — Cross-link unlinked pages
+## Step 6c — Cross-link unlinked pages
 
 For unlinked pages:
 
@@ -111,6 +189,18 @@ For unlinked pages:
 
 ---
 
-## Step 6 — Report
+## Step 7 — Report
 
 Show what was created or modified, and offer to run `/hypo:lint` to verify all new links resolve.
+
+---
+
+## Appendix — Legacy `--check-session-close`
+
+`--check-session-close` (read-only strict gate, same check PreCompact runs) is still supported as a probe-only verification. Use it when you only want to verify that today's session-close is complete without applying anything:
+
+```bash
+node <package-root>/scripts/crystallize.mjs --check-session-close [--hypo-dir="<path>"]
+```
+
+It reports any file as `missing` or `stale`. For an actual close, prefer `--apply-session-close --payload=<path>` (Step 3) — it bundles freshness + lint into one gate and is the documented dogfood path. (`parseArgs` only accepts the `--payload=<path>` spelling; a space-separated `--payload <path>` is silently ignored and triggers "payload is required".)