hypomnema 1.2.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.2.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.2.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개월 시점에서 페이지 수는 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/hooks/hypo-cwd-change.mjs

@@ -18,6 +18,7 @@ import {
   shouldSuggestProjectCreation,
   buildProjectSuggestionLine,
   recordSuggestionCooldown,
+  sanitizeProjForPrompt,
 } from './hypo-shared.mjs';
 
 const PROJECTS_DIR = join(HYPO_DIR, 'projects');
@@ -124,10 +125,13 @@ process.stdin.on('end', () => {
       }
       console.log(
         JSON.stringify(
-          buildOutput(`[WIKI: cwd changed → project=${newHit.proj}]\n\n${content}`, {
-            continue: true,
-            suppressOutput: true,
-          }),
+          buildOutput(
+            `[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
+            {
+              continue: true,
+              suppressOutput: true,
+            },
+          ),
         ),
       );
       return;

package/hooks/hypo-first-prompt.mjs

@@ -15,7 +15,7 @@
  */
 
 import { readFileSync, unlinkSync, existsSync } from 'fs';
-import { buildOutput, sessionMarkerPath } from './hypo-shared.mjs';
+import { buildOutput, sessionMarkerPath, sanitizeProjForPrompt } from './hypo-shared.mjs';
 
 const MARKER_TTL = 10 * 60 * 1000; // 10 min
 
@@ -52,16 +52,48 @@ process.stdin.on('end', () => {
     // fix #13: a cwd-change re-trigger says "Resuming"; a fresh session start
     // (default source) says "Previously working on".
     const verb = marker.source === 'cwd-change' ? 'Resuming' : 'Previously working on';
+    // marker.proj originates from a wiki directory name read by findProjectFiles;
+    // sanitize via the shared helper so a hand-crafted project name cannot close
+    // the wrapper tag, smuggle newlines/control chars, or inject conflicting
+    // directives into the resume contract (codex v2 review 2026-05-26).
+    const projSafe = sanitizeProjForPrompt(marker.proj);
+    // When there is no snapshot, the [HOT] / [SESSION STATE] context has nothing
+    // for the model to fill the placeholders with. Provide a concrete fallback
+    // line so the model doesn't leak literal `[one-line summary]` text on a
+    // first-ever session (codex v2 review 2026-05-26).
+    const exampleLine = hasSnapshot
+      ? `${verb} ${projSafe}: [one-line summary]. Continue with [next task]?`
+      : `${verb} ${projSafe}: no prior snapshot yet — first session. What would you like to start with?`;
+    const fillNote = hasSnapshot
+      ? `Replace the bracketed placeholders using the [HOT] / [SESSION STATE] ` +
+        `context already injected this session — do NOT emit the literal brackets.`
+      : `Use the line above verbatim — there is no prior snapshot to summarize.`;
 
     console.log(
       JSON.stringify(
         buildOutput(
-          `[WIKI SESSION START: project=${marker.proj}${snapshotNote}]\n` +
-            `Before addressing the user's message, lead your FIRST reply with exactly one line:\n` +
-            `"${verb} ${marker.proj}: <one-line summary>. Continue with <next task>?"\n` +
-            `Draw <one-line summary> and <next task> from the [HOT] / [SESSION STATE] ` +
-            `context already injected this session. Inject this line unconditionally — ` +
-            `even if the user's first message is unrelated or a simple question — then answer normally.`,
+          `<hypomnema-session-resume>\n` +
+            `[WIKI SESSION START: project=${projSafe}${snapshotNote}]\n` +
+            `\n` +
+            `Lead your FIRST reply this session with exactly one line in this shape:\n` +
+            `\n` +
+            `${exampleLine}\n` +
+            `\n` +
+            `${fillNote}\n` +
+            `\n` +
+            `Emit this line unconditionally on the first prompt, including when the ` +
+            `user's message is:\n` +
+            `  • a simple greeting ("안녕", "hi", "hello")\n` +
+            `  • a trivial question or unrelated topic\n` +
+            `  • a one-word reply\n` +
+            `\n` +
+            `Do not skip it, do not decide it is "not relevant", do not shorten the ` +
+            `reply to omit it. After the line, answer the user's actual message on the ` +
+            `following line(s) as normal.\n` +
+            `\n` +
+            `This is the Hypomnema session-resume contract — the user relies on this ` +
+            `line to confirm which project context is loaded.\n` +
+            `</hypomnema-session-resume>`,
           { continue: true, suppressOutput: true },
         ),
       ),

package/hooks/hypo-personal-check.mjs

@@ -241,7 +241,9 @@ process.stdin.on('end', () => {
     !gitStatus.clean ? gitStatus.reason : '',
     !hotStatus.clean ? hotStatus.reason : '',
     !closeFiles.ok ? closeFilesReason : '',
-    !lintOk ? `lint blockers: ${lintBlockers.map((b) => b.id).join(', ')}` : '',
+    !lintOk
+      ? `lint blockers: ${[...new Set(lintBlockers.map((b) => b.id || b.file))].join(', ')}`
+      : '',
     !designHistoryOk
       ? `design-history stale: ${lintW8.map((w) => w.file.split('/')[1]).join(', ')}`
       : '',

package/hooks/hypo-session-start.mjs

@@ -27,6 +27,7 @@ import {
   shouldSuggestProjectCreation,
   buildProjectSuggestionLine,
   recordSuggestionCooldown,
+  sanitizeProjForPrompt,
 } from './hypo-shared.mjs';
 import {
   defaultCachePath,
@@ -334,7 +335,7 @@ process.stdin.on('end', () => {
         console.log(
           JSON.stringify(
             buildOutput(
-              `${noticePrefix}[WIKI HOT CACHE: project=${hit.proj}]\n\n${parts.join('\n\n')}`,
+              `${noticePrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}]\n\n${parts.join('\n\n')}`,
               { continue: true, suppressOutput: true },
             ),
           ),
@@ -349,10 +350,13 @@ process.stdin.on('end', () => {
         );
         console.log(
           JSON.stringify(
-            buildOutput(`${noticePrefix}[WIKI HOT CACHE: project=${hit.proj}, no snapshot yet]`, {
-              continue: true,
-              suppressOutput: true,
-            }),
+            buildOutput(
+              `${noticePrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}, no snapshot yet]`,
+              {
+                continue: true,
+                suppressOutput: true,
+              },
+            ),
           ),
         );
       }

package/hooks/hypo-shared.mjs

@@ -24,6 +24,28 @@ export function sessionMarkerPath(sessionId) {
   return join(tmpdir(), `hypo-session-marker-${safe}.json`);
 }
 
+// ── project name sanitizer for prompt-facing interpolation ─────────────────
+// marker.proj is read from a wiki directory name (findProjectFiles) and
+// interpolated into LLM-facing additionalContext strings by multiple hooks.
+// A manually-crafted directory name could otherwise close a wrapping tag,
+// smuggle a newline, or inject conflicting instructions. Centralized so the
+// three injection sites stay in lock-step (codex v2 review 2026-05-26 —
+// addresses shared-helper concern across hypo-first-prompt / hypo-session-start
+// / hypo-cwd-change).
+//
+// Strips: angle brackets, control chars (C0 + C1), Unicode line separators
+// (U+2028 / U+2029), then collapses whitespace and caps length.
+export function sanitizeProjForPrompt(raw, fallback = 'unknown') {
+  const cleaned = String(raw || fallback)
+    .replace(/[<>\[\]]/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 80);
+  return cleaned || fallback;
+}
+
 // ── wiki root resolution ────────────────────────────────────────────────────
 
 function expandHome(p) {
@@ -221,7 +243,9 @@ export function resolveActiveProject(hypoDir) {
   if (!existsSync(hotPath)) return null;
   let content;
   try {
-    content = readFileSync(hotPath, 'utf-8');
+    // Strip HTML comments before parsing so the canonical-format example row
+    // in templates/hot.md (`<!-- Row format: ... -->`) is not picked up as data.
+    content = readFileSync(hotPath, 'utf-8').replace(/<!--[\s\S]*?-->/g, '');
   } catch {
     return null;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",

package/scripts/resume.mjs

@@ -37,7 +37,9 @@ function resolveActiveProject(hypoDir) {
   const hotPath = join(hypoDir, 'hot.md');
   if (!existsSync(hotPath)) return null;
 
-  const content = readFileSync(hotPath, 'utf-8');
+  // Strip HTML comments before parsing so the canonical-format example row
+  // in templates/hot.md (`<!-- Row format: ... -->`) is not picked up as data.
+  const content = readFileSync(hotPath, 'utf-8').replace(/<!--[\s\S]*?-->/g, '');
   // Canonical hot.md uses wikilinks: | name | date | [[projects/slug/hot]] |
   // Pick the most recent row by the date column when present.
   const wikiRows = [
@@ -60,6 +62,8 @@ function resolveActiveProject(hypoDir) {
   let latest = null;
   let latestMtime = 0;
   for (const p of readdirSync(projectsDir)) {
+    // Skip the scaffold project init.mjs writes — it isn't a real active project.
+    if (p === '_template') continue;
     const ssPath = join(projectsDir, p, 'session-state.md');
     if (!existsSync(ssPath)) continue;
     const mtime = statSync(ssPath).mtimeMs;

package/templates/hot.md

@@ -14,7 +14,7 @@ tags: [wiki, operations]
 
 | Project | Last Session | Hot Cache |
 |---|---|---|
-<!-- Row format: | Project Name | YYYY-MM-DD | [[projects/slug/hot]] | -->
+<!-- Row format: | Project Name | YYYY-MM-DD | projects/<slug>/hot (wikilink) | -->
 <!-- col2 date is rebuilt from projects/<slug>/hot.md frontmatter on each session close -->
 
 ## Session Start Checklist

package/templates/hypo-config.md

@@ -1,7 +1,7 @@
 ---
 title: Hypomnema Config
 type: config
-version: "1.2.0"
+version: "1.2.1"
 created: YYYY-MM-DD
 ---