hypomnema 1.2.0 → 1.3.0

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.2.0",
+      "version": "1.3.0",
       "homepage": "https://github.com/sk-lim19f/Hypomnema"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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개월 시점에서 페이지 수는 sub-linear로 늘고 교차 링크는 super-linear로 늘어납니다.
-- **컨텍스트 전환 0.** 이미 Claude Code 안에 있습니다. 위키는 슬래시 명령 하나 떨어진 거리 — 새 탭도, 새 앱도, 새 로그인도 없습니다.
-- **미래 안전한 저장소.** 평문 마크다운 + git이라는 의미는 — 20년 뒤에도 읽을 수 있고, 오프라인에서도 grep 되며, 언제든 다른 도구로 옮겨갈 수 있고, 아직 만나지 않은 미래의 AI 어시스턴트도 그대로 이해할 수 있다는 뜻입니다.
+- **저장이 아니라 합성.** 끝까지 읽지도 못한 글들의 무덤이 쌓이지 않습니다. `/hypo:ingest`는 매번 구조화된 페이지를 만들고, 같은 주제의 다음 인제스트는 새 페이지가 아닌 *기존 페이지의 갱신*으로 들어갑니다.
+- **밀도가 복리로 자란다.** 소스 100개짜리 위키가 단절된 페이지 100개로 끝나면 의미가 없습니다. 실사용 3개월 시점이면 페이지 수는 소스 증가보다 천천히 늘고, 교차 링크는 오히려 더 빠르게 늘어납니다.
+- **맥락 전환이 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` | session-close 체크리스트(steps 1~6) + 요청 시 초안 합성(steps 7~11) | 비자명한 세션 종료 시 |
-| `/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개)
 
 | 훅 | 이벤트 | 역할 |
 |---|---|---|
@@ -201,9 +238,17 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 | `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,17 +342,17 @@ Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실
 
 위키 루트에 `hypo-config.md`를 두면 환경변수 없이도 기기 간 이식이 가능합니다.
 
-`.hypoignore`는 훅이 무시할 경로를 정의합니다 (기본: `*.pdf`, `*.zip`, `*.pem`, `*.env` 등). 직접 편집하면 됩니다 — privacy mode 플래그는 없습니다. 단일 파일, 단일 진실 소스.
+`.hypoignore`는 훅이 무시할 경로를 정의합니다 (기본: `*.pdf`, `*.zip`, `*.pem`, `*.env` 등). 직접 편집하면 됩니다 — privacy mode 플래그는 없습니다. 파일 하나가 모든 결정을 담는 단일 원천 구조입니다.
 
-> **Provider 전송 디스클레이머.** Hypomnema 훅은 위키 콘텐츠를 Claude Code의 `additionalContext`로 emit하며, 이는 프롬프트의 일부로 Claude 모델 provider에 전송됩니다. `.hypoignore`는 모든 콘텐츠 주입 훅(`hypo-file-watch`, `hypo-session-start`, `hypo-cwd-change`, `hypo-lookup`) 및 `ingest`에서 강제되지만, `.hypoignore`에 매칭되지 *않는* 파일은 전송 대상입니다. (`hypo-auto-stage`/`hypo-auto-commit`은 git staging 훅이며 주입 지점이 아니지만, staging 판단에도 `.hypoignore`를 준수합니다.) 위키에 비밀을 두지 말고, `HYPO_DIR` 아래 민감 콘텐츠를 저장하기 전 `.hypoignore` 패턴을 검토하세요.
+> **모델 사업자에게 전송되는 범위 안내.** 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`으로 보존) |
 
 ---
@@ -322,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:
@@ -187,7 +224,7 @@ Eight commands cover the full capture → retrieval → consolidation cycle.
 | `/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 |
 |---|---|---|
@@ -201,9 +238,17 @@ Eight commands cover the full capture → retrieval → consolidation cycle.
 | `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
 
@@ -300,13 +346,13 @@ Place a `hypo-config.md` at the wiki root to make it portable across machines wi
 
 > **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. 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/).
+> **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/crystallize.md

@@ -11,7 +11,20 @@ You are running `/hypo:crystallize`. This command serves two purposes:
 
 ## Step 1 — Detect context
 
-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.
+If the user invoked `/hypo:crystallize` to close a session (phrases like "세션 종료", "오늘 작업 마무리", "session close", or "wrap up"), run Step 1a (advisory reflections) then Steps 2–4 (session-close mechanical apply + recovery) **before** the synthesis scan. Otherwise skip to Step 5.
+
+---
+
+## Step 1a — Session-close advisory reflections
+
+Before composing the payload (Step 2), run these four reflections and surface each to the user. Every one is **advisory** (ADR 0029 identity guard) — the user confirms or declines, and none performs an automatic action, writes a file on its own, or bypasses the mandatory gate.
+
+1. **Trivial-session check (#44)** — Was this session trivial (a single bug fix, a single-file edit, or Q&A with no durable artifact)? If so, recommend skipping session-close: *"이 세션은 trivial해 보입니다 — session-close를 건너뛸까요?"* and proceed only if the user wants a close. A trivial skip is a recommendation, **not** a bypass: it must not mark the session closed, must not run `--mark-session-closed`, and must not claim `/compact` can pass. Any real close still requires all 5 mandatory files.
+2. **ADR-candidate check (#41)** — Did this session make an architectural or design decision (a new pattern, a tradeoff chosen, a convention established)? If yes, ask whether it warrants an ADR and, if so, capture that intent in the `sessionLog` entry you compose in Step 2. If nothing rose to ADR level, record `ADR 없음 — <one-line reason>` in that same `sessionLog` entry. **Never auto-write an ADR file** — recording the decision (or its absence) in the session-log payload is the only action here.
+3. **design-history staleness check (#42)** — If `projects/<name>/design-history.md` exists and this session changed design decisions it does not yet reflect, recommend updating it (the W8 lint warning flags this mechanically; an active-project W8 can also block at PreCompact). If the file does not exist, skip silently — do **not** create it just for this check. Never auto-update it.
+4. **Ingest check (#43)** — Did this session consume trustworthy external knowledge (a fetched URL, official docs, or code you verified directly)? If so, recommend running `/hypo:ingest` to capture it under `sources/`. Proceed only on the user's confirmation.
+
+These are judgment calls; when uncertain, surface the question rather than skip it. None of the four blocks the close or writes on its own.
 
 ---
 
@@ -89,10 +102,14 @@ synthesis (no session-close intent) — the marker is then simply not written.
 | `--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):**
+**Two lint gates run automatically (fix #40), scoped to the files this close writes:**
+
+Both gates judge only the **payload files** (the 5 mandatory close files + `open-questions.md`). Lint debt in other projects or shared `pages/` this close did not author is reported as a non-blocking `notices[]` entry, never gated — so an unrelated broken page elsewhere cannot block your close.
+
+1. **Preflight** — `lint.mjs --json` runs **before** any payload bytes are written. Errors in overwrite targets (sessionState / projectHot / rootHot / openQuestions) are filtered (about to be replaced). Errors in an **append target** (session-log / log.md) still block (appending can't repair existing corruption) → exit 1 with `stage='preflight-lint'`. Errors outside the payload files → `notices[]`, apply proceeds.
+2. **Post-apply** — lint re-runs after the writes. Blocks only on **errors** in payload files (a payload-introduced malformed body / bad frontmatter); pre-existing errors elsewhere → `notices[]`. A lint crash (unparseable output) always blocks. Broken wikilinks are lint **warnings** (W4 — forward references to planned pages are normal) and are not gated here. Surfaces as `stage='post-apply-lint'` (or `'post-apply-verification+lint'` if freshness also fails).
 
-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).
+> **Manual close (direct Write tool calls)** clears the Stop-chain block via `--mark-session-closed --session-id=<id>`. Pass `--transcript-path=<path>` (the Stop hook surfaces it in its block message) so the marker is refused when a file **this session edited** still has lint errors — keeping the marker coherent with the PreCompact gate. Without `--transcript-path` it falls back to freshness + clean-git only (lint left to PreCompact).
 
 ---
 
@@ -102,9 +119,9 @@ The result JSON includes a `stage` field when `ok: false`. Branch on it:
 
 | `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. |
+| `preflight-lint` | A payload file (append target — session-log / log.md) has a pre-existing blocking lint error. | Fix the lint error in that file, then re-run. No payload bytes were written. (Debt outside the payload files is a non-blocking notice, not this stage.) |
 | `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-lint` | The payload introduced an error-level lint blocker in a payload file (malformed body / bad frontmatter), or lint crashed. | Fix the offending content in the payload, then re-run. (Broken wikilinks are W4 warnings — not gated.) |
 | `post-apply-verification+lint` | Both above. | Fix both; re-run. |
 
 Once `ok: true`, report:

package/commands/feedback.md

@@ -68,7 +68,7 @@ node <package-root>/scripts/feedback.mjs \
 
 When `--targets` includes `claude-learned`, `--global-summary` and `--promote-to-global` are required (and `--scope=global --tier=L1`).
 
-> **`scope: project:<project-id>` 주의 (v1.2.0).** `<project-id>`는 `feedback-sync`가 resolve한 project-id와 정확히 일치해야 한다 (default: cwd의 `/`,`.` → `-` 치환; `--project-id=<id>` 로 override). 일치하지 않으면 그 페이지는 해당 project의 MEMORY로 projection되지 **않는다** (silent skip — lint error 아님). 다만 현재 lint scope regex(`^project:[a-z0-9][a-z0-9-]*$`)는 cwd-derived id 형식(`-Users-...`)을 거부하므로, **`project:*` scope를 사용하려면 slug-safe id로 `--project-id=<slug>`를 override해서 wiki 디렉터리도 그 id에 맞추는 운영 패턴이 필요하다**. resolved-id ↔ slug 정합화는 v1.3.0 트랙에서 다룸.
+> **`scope: project:<project-id>` 주의.** `<project-id>`는 `feedback-sync`가 resolve한 project-id와 정확히 일치해야 한다 (default: cwd의 `/`,`.` → `-` 치환; `--project-id=<id>` 로 override). 일치하지 않으면 그 페이지는 해당 project의 MEMORY로 projection되지 **않는다** (silent skip — lint error 아님). v1.3.0부터 scope regex(`^(global|project:[A-Za-z0-9_-]+)$`)가 cwd-derived id 형식(`-Users-...`)을 그대로 허용하므로 lint 통과를 위해 `--project-id=<slug>`를 override할 필요는 없다. 단 cwd에 공백 등 `[A-Za-z0-9_-]` 밖 문자가 있으면 그 id는 여전히 거부되니 그때만 `--project-id=<id>`로 override한다.
 
 On a real (non-dry-run) write, the script automatically runs `feedback-sync --write` to refresh MEMORY.md / CLAUDE.md. If that post-step reports drift it prints a one-line warning — the page is still saved; reconcile with `hypomnema feedback-sync --check`.
 

package/docs/CONTRIBUTING.md

@@ -119,10 +119,37 @@ If you need to share new logic, prefer extending an existing helper over adding
 ## Testing
 
 ```bash
-npm test       # tests/runner.mjs — unit + smoke + contract tests
-npm run lint   # scripts/lint.mjs — frontmatter + wikilink validation + W8 (design-history stale vs session-log)
+npm test           # tests/runner.mjs — unit + smoke + contract tests
+npm run lint       # scripts/lint.mjs — frontmatter + wikilink validation + W8 (design-history stale vs session-log)
+npm run fix:verify # Phase 1 of learned_behavior #6 — verifies fix #N status claims in
+                   # a wiki spec against `// @fix #N: <test-name>` anchors in
+                   # tests/runner.mjs. Maintainer dogfood; needs a local wiki at
+                   # $HYPO_DIR or ~/hypomnema. Does NOT grep ADR core decision lines.
 ```
 
+> **`fix:verify` needs an explicit `--spec`.** The default path
+> (`projects/hypomnema/spec-v1.2.md`) is now a `type: reference` redirect stub —
+> the real spec moved to `archive/`. Running the bare command fails with
+> `STUB_SPEC` by design (a stub carries zero status claims, so greening it would
+> be vacuous). Point it at the real spec:
+>
+> ```bash
+> npm run fix:verify -- --spec ~/hypomnema/projects/hypomnema/archive/spec-v1.2.md
+> ```
+
+### `// @fix #N:` anchor convention
+
+When a test verifies behavior tied to a numbered fix in the wiki spec, add an anchor immediately above the `suite(...)` or `test(...)` call:
+
+```js
+// @fix #25: replay-compact-guard-detects-slash-clear: /clear with incomplete wiki → WIKI_AUTOCLOSE
+test('replay-compact-guard-detects-slash-clear: /clear with incomplete wiki → WIKI_AUTOCLOSE', () => { ... });
+```
+
+The anchor's body must be the EXACT test name (whole rest of the line; no comma splitting). Multiple anchor lines per fix # accumulate. For fixes whose verification is behavioral / prompt-driven (no automated test by design), use the sentinel `// @fix #N: NO_AUTO_TEST`.
+
+`npm run fix:verify` reads these anchors plus the spec status claims and reports any drift (`NO_ANCHOR`, `MISSING_TEST`, `FAILING_TEST`, `ORPHAN_ANCHOR`, `STUB_SPEC`). Plain `// fix #N: …` comments without the `@` prefix are treated as prose and ignored by the verifier.
+
 The test runner uses only Node.js built-ins. Tests create scoped temp directories and clean up after themselves; you can run the suite without any environment setup.
 
 When adding a feature, add a corresponding test. For hook-event behavior that's hard to unit-test, document the manual verification step in the PR description (see the manual verification section below).
@@ -139,6 +166,34 @@ Some hook behavior is only observable inside a Claude Code session. Document the
 
 ---
 
+## Pre-commit auto-format hook
+
+`npm install` in this checkout installs a git `pre-commit` hook that runs `prettier --write` on staged files only. The hook is **non-blocking**: formatter failures print a notice but the commit still proceeds. The only block is when `git add` itself fails during restage (true index corruption).
+
+**Requirements**: Git ≥ 2.13 (uses `--absolute-git-dir`; `--git-common-dir` is 2.5+).
+
+**Path-locked to your checkout.** The shim embeds the absolute paths of your `HYPOMNEMA_ROOT` and `.git/` directory at install time. If you `mv` the checkout, re-run `npm install` to regenerate the shim — until then it safely no-ops.
+
+**Main worktree only.** `git worktree add` checkouts silently skip — the shared `.git/hooks/pre-commit` can only point at one embedded root at a time. Commit from the main worktree to get auto-format, or accept the no-op in linked worktrees.
+
+**CI is skipped.** `npm ci` runs `prepare`, but the installer detects `CI=true` and exits 0 without touching `.git/hooks/`. CI runs never mutate hooks.
+
+**Symlink-safe.** If `.git/hooks/` is a symlink, or an existing `pre-commit` is a symlink, the installer refuses to write through it.
+
+**Shared `core.hooksPath` safe.** The shim verifies both `--show-toplevel` and `--absolute-git-dir` against the embedded values before executing. Foreign repos that share your global `core.hooksPath` will silently no-op.
+
+**Env-override defense.** The Node side strips every `GIT_*` env from `git rev-parse --local-env-vars` (plus `GIT_NAMESPACE`, `GIT_CEILING_DIRECTORIES`, `GIT_CONFIG_*`) before its own git spawns. Inherited `GIT_INDEX_FILE` is preserved **only** when invoked from the installed shell shim (signalled via a sentinel env var). Direct `node scripts/pre-commit-format.mjs` invocation drops `GIT_INDEX_FILE` and falls back to the default `.git/index`, closing the class of attacks that try to drive the formatter against a crafted alternate index.
+
+**Existing non-marker pre-commit?** If you have your own `pre-commit` hook (no `# hypomnema-pre-commit-marker v1` on line 2), the installer logs a notice and never overwrites it.
+
+**Skip a single commit**: `git commit --no-verify`. AI agents must not use this without explicit user authorization.
+
+**Verbose install logs**: `HYPOMNEMA_HOOK_VERBOSE=1 npm install` prints skip/install reasons to stderr.
+
+**Distinction from `hooks/hypo-pre-commit.mjs`**: that file is the git pre-commit worker template that `scripts/init.mjs` installs into `<wiki>/.git/hooks/pre-commit` when a user runs `hypomnema init` in their own wiki repo. It lives in the *user's wiki* repo, not in this package repo. The two hooks never interact.
+
+---
+
 ## Branch and commit conventions
 
 - One logical change per branch.
@@ -177,27 +232,57 @@ Hypomnema uses semver. Releases are automated via `release.yml` on `v*` tag push
 
 ### Cutting a release
 
+Every Hypomnema release must carry a Korean summary alongside the English body
+in **both** the CHANGELOG section AND the git tag annotation. The release
+workflow enforces this with `scripts/check-bilingual.mjs`; lightweight tags or
+a missing `### 한글 요약` section will block `npm publish`.
+
 ```bash
-# 1. Bump the version (writes package.json + CHANGELOG.md)
-node scripts/bump-version.mjs <patch|minor|major>
+# 1. Bump the version across package.json, plugin.json, marketplace.json,
+#    and templates/hypo-config.md. Takes a concrete semver (not patch/minor/major).
+node scripts/bump-version.mjs <new-semver>   # e.g. 1.2.2 or 1.3.0-rc.1
+
+# 2. Edit CHANGELOG.md — the new section MUST include a "### 한글 요약"
+#    sub-section with at least 10 Hangul characters of real summary text.
+$EDITOR CHANGELOG.md
 
-# 2. Review the diff and edit CHANGELOG.md if needed
-git diff
+# 3. Verify locally before tagging (same check that runs in CI)
+node scripts/check-bilingual.mjs --changelog
 
-# 3. Commit
+# 4. Commit
 git add package.json CHANGELOG.md
 git commit -m "chore: release v<version>"
 
-# 4. Tag and push
-git tag v<version>
+# 5. Tag with an ANNOTATED tag — never a lightweight tag.
+#    Annotation body shape: English summary, then "---" on its own line,
+#    then a Korean summary block.
+git tag -a v<version> -m "$(cat <<'EOF'
+Hypomnema v<version> — <one-line English summary>
+
+<a few lines of English body — what shipped, links, etc.>
+
+---
+
+Hypomnema v<version> — <한 줄 한글 요약>
+
+<몇 줄의 한글 요약 본문.>
+EOF
+)"
+
+# 6. Verify the tag annotation locally (same check that runs in CI)
+node scripts/check-bilingual.mjs --tag v<version>
+
+# 7. Push
 git push origin main --tags
 ```
 
 The `release.yml` workflow then:
 
 1. Verifies the tag matches `package.json` version.
-2. Runs `npm test` and `npm run lint`.
-3. Publishes to npm with `npm publish --access public --provenance`.
+2. Validates the CHANGELOG section AND the tag annotation are bilingual
+   (`scripts/check-bilingual.mjs`).
+3. Runs `npm test` and `npm run lint`.
+4. Publishes to npm with `npm publish --access public --provenance`.
 
 `NPM_TOKEN` must be set as a repository secret.