hypomnema 1.0.1 → 1.1.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.0.1",
+      "version": "1.1.0",
       "homepage": "https://github.com/sk-lim19f/Hypomnema"
     }
   ]

package/.claude-plugin/plugin.json

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

package/README.ko.md

@@ -10,17 +10,19 @@
 [![npm downloads](https://img.shields.io/npm/dm/hypomnema?color=blue)](https://www.npmjs.com/package/hypomnema)
 [![Node.js](https://img.shields.io/node/v/hypomnema?color=43853d&logo=node.js&logoColor=white)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-51%2F51-brightgreen)](tests/runner.mjs)
+[![CI](https://github.com/sk-lim19f/Hypomnema/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sk-lim19f/Hypomnema/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/sk-lim19f/Hypomnema?style=flat&color=yellow)](https://github.com/sk-lim19f/Hypomnema/stargazers)
 
 **Claude Code를 위한 LLM 네이티브 개인 위키. 복리로 성장하는 지식.**
 
-_노트하지 마세요. Claude가 합성하게 하세요._
+_Claude가 노트하게 만드세요 — 그리고 그게 실제로 일어나는지 측정하세요._
 
 [빠른 시작](#빠른-시작) • [다른 시스템과의 비교](#다른-시스템과의-비교) • [설계 결정](#설계-결정) • [기능](#기능) • [아키텍처](docs/ARCHITECTURE.md) • [기여](docs/CONTRIBUTING.md)
 
 > Andrej Karpathy의 "LLM 네이티브 위키" 스케치에서 영감을 받아, 10개월간의 개인 운영 경험으로 다듬어진 도구입니다. 캡처 → 합성 → 검색 → 세션 재개로 이어지는 전체 라이프사이클을 Claude Code 명령어와 라이프사이클 훅으로 제공합니다.
 
+> **현재 상태 vs. v2 비전.** v1.0.1(현재)은 트리거 모델을 정직하게 밝힙니다: 대부분의 위키 동작 — 인제스트, 쿼리, 세션 클로즈 — 은 **명시적 `/hypo:*` 커맨드**로 시작되며, 일부 훅이 자동 staging·세션 상태 주입·룩업 신호를 처리합니다. v2 thesis는 *완전 자율* — Claude가 요청 없이 위키를 읽고·쓰고·합성하는 상태입니다. **v1.1.0**은 그 램프의 첫 단계로, 자율을 주장하는 대신 **observability 점수**를 출력해 세션당 위키가 실제로 얼마나 쓰였는지(ingest 수, query 수, session-close 비율, citation 비율)를 측정·공개합니다. v2 구현 이전에 자율 vs. 수동 비율을 사용자가 직접 확인할 수 있게 하기 위함입니다.
+
 ---
 
 ## 빠른 시작
@@ -105,6 +107,7 @@ Hypomnema         ───►  합성 · 마크다운 · git · 훅 · 로컬
 | **포맷** | 평문 마크다운 + frontmatter | 마크다운 | 독자 포맷 | 벡터 스토어 | 독자 포맷 | HTML |
 | **백엔드** | 로컬 파일 + git | 로컬 파일 | SaaS | 서비스 / DB | SaaS | 서비스 |
 | **행동 튜닝** | `/hypo:feedback` → 영구 규칙 | 없음 | 없음 | 없음 | 일부 | 없음 |
+| **자율 동작(auto-behavior)** | 현재는 명시적 `/hypo:*` 트리거 기반; **v1.1에서 observability 점수 도입**, v2 목표 = 완전 자율 | 없음 | 없음 | 없음 | 블랙박스 | 없음 |
 | **셋업 비용** | 명령 1개 | 설치 1번 | 가입 | 파이프라인 구축 | 가입 | 레포 연결 |
 | **락인** | 0 (마크다운 + git) | 낮음 | 높음 | 중간 | 높음 | 중간 |
 
@@ -295,6 +298,8 @@ Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실
 
 `.hypoignore`는 훅이 무시할 경로를 정의합니다 (기본: `*.pdf`, `*.zip`, `*.pem`, `*.env` 등). 직접 편집하면 됩니다 — privacy mode 플래그는 없습니다. 단일 파일, 단일 진실 소스.
 
+> **git sync 범위.** Hypomnema는 `~/hypomnema/` 위키 자체만 git sync합니다. Claude Code 설정(`~/.claude/`)은 의도적으로 Hypomnema가 **관리하지 않습니다** — agent·skill·settings의 기기 간 동기화는 [chezmoi](https://www.chezmoi.io/) 같은 별도 dotfiles 매니저 사용을 권장합니다.
+
 ### `/hypo:*` 커맨드는 어디서 오는가?
 
 | 설치 경로 | 슬래시 커맨드 위치 |
@@ -315,7 +320,7 @@ Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실
 
 ## 상태
 
-- **테스트:** 51 / 51 통과 — `tests/runner.mjs`
+- **테스트:** `npm test` 참조 — lane이 ship될 때마다 카운트가 변하므로 러너가 단일 진실 공급원
 - **CI:** 7개 독립 job (test matrix, lint, init/upgrade snapshots, replay, hypo-absent, uninstall-smoke)
 - **릴리스:** `v*` 태그 push 시 `npm publish --provenance` 자동 실행
 

package/README.md

@@ -10,17 +10,19 @@ English | [한국어](README.ko.md)
 [![npm downloads](https://img.shields.io/npm/dm/hypomnema?color=blue)](https://www.npmjs.com/package/hypomnema)
 [![Node.js](https://img.shields.io/node/v/hypomnema?color=43853d&logo=node.js&logoColor=white)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-51%2F51-brightgreen)](tests/runner.mjs)
+[![CI](https://github.com/sk-lim19f/Hypomnema/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sk-lim19f/Hypomnema/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/sk-lim19f/Hypomnema?style=flat&color=yellow)](https://github.com/sk-lim19f/Hypomnema/stargazers)
 
 **LLM-native personal wiki for Claude Code. Knowledge that compounds.**
 
-_Don't take notes. Let Claude synthesize them._
+_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.
 
+> **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 Start
@@ -105,6 +107,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 |
 | **Setup cost** | One command | One install | Sign-up | Pipeline build | Sign-up | Repo connect |
 | **Lock-in** | Zero (markdown + git) | Low | High | Medium | High | Medium |
 
@@ -295,6 +298,8 @@ 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/).
+
 ### Where do `/hypo:*` commands live?
 
 | Install path | Slash commands served from |
@@ -315,7 +320,7 @@ No external services. No API keys. No vector databases.
 
 ## Status
 
-- **Tests:** 51 / 51 passing — see `tests/runner.mjs`
+- **Tests:** see `npm test` — exact totals shift as lanes ship, so the runner is the source of truth
 - **CI:** 7 independent jobs (test matrix, lint, init/upgrade snapshots, replay, hypo-absent, uninstall-smoke)
 - **Release:** `npm publish --provenance` on `v*` tag push
 

package/commands/audit.md

@@ -0,0 +1,46 @@
+---
+description: Run the observability audit on recent sessions and (optionally) write the weekly report
+---
+
+You are running `/hypo:audit`. Inspect recent Claude Code sessions to see how much of the wiki's value motion is actually happening (search, ingest, citation, feedback), then either show the result inline or write a weekly observability page.
+
+## What this shows
+
+- Per-session metrics — search count, ingest count, URL mentions, feedback count
+- Classification — `normal` / `search-0` / `search-many` / `ingest-missed` / `staleness-skip`
+- Optional weekly aggregation with an autonomy score (heuristic v0)
+
+Definition: [[pages/observability/_index]].
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+
+If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
+
+---
+
+## Step 2 — Decide the mode
+
+- **Per-session view (default)** — show recent sessions with metrics + classification:
+  ```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`:
+  ```bash
+  node <package-root>/scripts/weekly-report.mjs [--hypo-dir="<path>"] [--week=YYYY-WW] --write
+  ```
+- **JSON for tooling** — append `--json` to either script.
+
+---
+
+## Step 3 — Report results
+
+Show the output verbatim. Then add a brief interpretation:
+
+- If `staleness-skip` dominates: "Most sessions audited are older than 30 days — score reflects backlog, not current behavior."
+- If `search-0` count is high: "Sessions ran without consulting the wiki — consider whether `/hypo:query` was the right reflex."
+- If `ingest-missed` is non-zero: "Sessions discussed URLs but no `/hypo:ingest` ran — those captures got lost."
+- Otherwise: "Audit window looks healthy; weekly report committed to the wiki for trend tracking."

package/docs/ARCHITECTURE.md

@@ -53,7 +53,7 @@ hypomnema/
 │   ├── Home.md, Overview.md, hypo-automation.md, hypo-help.md
 │   ├── pages/_index.md
 │   └── projects/_template/
-├── tests/runner.mjs          ← no-dependency test runner (51 tests)
+├── tests/runner.mjs          ← no-dependency test runner
 ├── docs/                     ← ARCHITECTURE.md, CONTRIBUTING.md
 ├── .claude-plugin/plugin.json← plugin manifest
 └── package.json              ← npm metadata, no runtime deps
@@ -100,7 +100,7 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 | `UserPromptSubmit` | `hypo-first-prompt.mjs` → `hypo-lookup.mjs` → `hypo-compact-guard.mjs` |
 | `PreCompact` | `hypo-personal-check.mjs` |
 | `PostToolUse` (Write/Edit) | `hypo-auto-stage.mjs` |
-| `Stop` | `hypo-hot-rebuild.mjs` → `hypo-auto-commit.mjs` |
+| `Stop` | `hypo-hot-rebuild.mjs` → `hypo-session-record.mjs` → `hypo-auto-commit.mjs` |
 | `CwdChanged` | `hypo-cwd-change.mjs` |
 | `FileChanged` | `hypo-file-watch.mjs` |
 
@@ -113,9 +113,10 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 | `hypo-lookup` | BM25 search over the wiki on every prompt. **HIT** → inject top-3 page snippets (≤2000 chars each, with verify-by-date warnings). **MISS** → emit closest-slug signal that prompts Claude to research + `/hypo:ingest` |
 | `hypo-compact-guard` | Detect `/compact` invocations → enforce session-close checklist before allowing compact |
 | `hypo-personal-check` | PreCompact validation: lint blockers, uncommitted changes, missing session-log entries → block compact |
-| `hypo-auto-stage` | After Write/Edit on a wiki path, run `git add` (filtered by `.hypoignore`) |
-| `hypo-hot-rebuild` | At session stop, regenerate root `hot.md` from recent activity |
-| `hypo-auto-commit` | At session stop, commit staged changes + `git pull --rebase` + `git push` (silent fail on missing remote) |
+| `hypo-auto-stage` | After Write/Edit on a wiki path, run `git add` (skips paths matching `.hypoignore`) |
+| `hypo-hot-rebuild` | At session stop, regenerate root `hot.md` from recent activity; emit growth metrics + cache for next SessionStart |
+| `hypo-session-record` | At session stop, append `{session_id, transcript_path, recorded_at, cwd}` to `.cache/sessions/index.jsonl` (primary source for the observability audit) |
+| `hypo-auto-commit` | At session stop, filter changed paths through `.hypoignore`, commit non-ignored changes, `git pull --no-rebase` + `git push` (silent fail on missing remote) |
 | `hypo-cwd-change` | When working directory changes, re-resolve the active project and inject its `hot.md` |
 | `hypo-file-watch` | Notify on external wiki edits so the in-session view stays consistent |
 
@@ -289,8 +290,9 @@ SessionStart
   │     └─► hypo-cwd-change.mjs (re-inject project hot.md)
   │
   └─► Stop
-        ├─► hypo-hot-rebuild.mjs (regenerate root hot.md)
-        └─► hypo-auto-commit.mjs (commit + pull --rebase + push)
+        ├─► hypo-hot-rebuild.mjs (regenerate root hot.md + growth cache)
+        ├─► hypo-session-record.mjs (append .cache/sessions/index.jsonl)
+        └─► hypo-auto-commit.mjs (.hypoignore-filtered stage + commit + pull + push)
 ```
 
 ---
@@ -307,6 +309,78 @@ Promotion is intentionally manual to keep `<learned_behaviors>` curated. The pip
 
 ---
 
+## Observability (v1.1)
+
+v1.1 ships an **observability wedge** — the wiki measures whether it's actually being used per session, rather than claiming autonomy it can't yet deliver.
+
+### Data flow
+
+```
+Stop hook (hypo-session-record.mjs)
+    │  appends one JSONL entry per session
+    ▼
+<hypo-root>/.cache/sessions/index.jsonl   ← primary source
+    │
+    ▼
+scripts/session-audit.mjs                  ← per-session metrics + classification
+    │
+    ▼
+scripts/weekly-report.mjs                  ← aggregated weekly autonomy score
+    │
+    ▼
+pages/observability/<YYYY-WW>.md           ← committed report (heuristic v0)
+```
+
+### Transcript dual-source (ADR 0019)
+
+`session-audit.mjs` reads transcripts from two locations, in priority order:
+
+1. **Primary:** `<hypo-root>/.cache/sessions/index.jsonl` — written by the Stop hook `hypo-session-record.mjs`. Each line: `{ session_id, transcript_path, recorded_at, cwd }`.
+2. **Fallback:** `~/.claude/projects/<encoded>/*.jsonl` — scanned when the index is missing or empty (legacy / freshly-installed wikis).
+
+### Classification
+
+| Class | Rule |
+|---|---|
+| `staleness-skip` | `recorded_at` older than `--max-age-days` (default 30) |
+| `ingest-missed` | `urls >= 2` and `ingest_count == 0` |
+| `search-many`   | `search_count >= 5` (heavy retrieval; suggests missing synthesis) |
+| `search-0`      | `search_count == 0` |
+| `normal`        | otherwise |
+
+Counted tool names: `Grep`, `WebSearch`, `WebFetch`. Counted slash commands: `/hypo:query`, `/hypo:ingest`, `/hypo:feedback`. A single transcript record contributes to exactly one of (tool-use search OR text-based command search) — `computeMetrics` short-circuits after a tool-use match to prevent double counting.
+
+### Autonomy score (heuristic v0)
+
+`weekly-report.mjs` aggregates the week's results into a 0–100 score. The score is **clamped to `[0, 100]`** and skips `staleness-skip` sessions. Formula sketch (see `pages/observability/_index.md` for the formal definition):
+
+```
+numerator   = Σ min(search,3) + ingest*3 + feedback*2
+denominator = Σ 1   + (urls > 0 ? min(urls,5)*2 : 0)
+score       = clamp(round(num/den * 100), 0, 100)
+```
+
+The score is a **proxy, not ground truth**. The four-week baseline plan (capture v0 numbers, then revisit with LLM-judge classification before v2) is recorded in the same `_index.md`.
+
+### Privacy
+
+The observability pipeline reads but never republishes raw transcripts. Weekly reports only emit `session_id` plus aggregate counts — no transcript content, no URLs, no tool inputs. Transcripts themselves live under `~/.claude/projects/` or `.cache/sessions/` which `.hypoignore` already excludes from any sync.
+
+### Growth metrics (Lane B)
+
+A separate, lightweight counter — distinct from the audit pipeline — runs at every Stop / SessionStart pair:
+
+- **Stop** (`hypo-hot-rebuild.mjs`) computes `{ addedPages, updatedPages, newWikilinks }` by reading `git status --porcelain` plus a conditional `git diff HEAD --unified=0`, writes the result to `<hypo-root>/.cache/last-session-growth.json`, and echoes one line to stderr.
+- **SessionStart** (`hypo-session-start.mjs`) reads the cache and surfaces the same line in both stderr (cyan) and the LLM's `additionalContext` so user and model see the same "직전 세션" prefix.
+
+If `git status` shows no `.md` changes, the diff step is skipped — Stop hook fast path.
+
+### Citation convention
+
+The six writer-side skills (`crystallize`, `query`, `ingest`, `verify`, `graph`, `lint`) carry an identical footer instructing Claude to cite wiki pages inline as `[[page-slug]]`. The audit script counts these citations as a "wiki was actually consulted" signal in future iterations.
+
+---
+
 ## Privacy & exclusions
 
 `.hypoignore` is the **only** privacy mechanism. The v1.0 `personal / shared / public` mode matrix was deleted in v1.1 — every privacy decision turned out to be a per-path question, and a single ignore file handles per-path natively.
@@ -329,9 +403,9 @@ Default patterns: `*.pdf`, `*.zip`, `*.pem`, `*.env`, `*.key`, `*.crt`, `*creden
 | `upgrade.mjs` regression | ~10 (includes migration fixture) |
 | `lint.mjs` (fix / json / session-state) | ~10 |
 | Misc (`expandHome`, `resolveHypoRoot`, …) | ~remainder |
-| **Total** | **51 / 51 PASS** |
+| **Total** | Run `npm test` for the live count |
 
-Run with `npm test`. The runner uses only Node.js built-ins; tests create scoped temp dirs and clean up after themselves.
+Run with `npm test`. The runner uses only Node.js built-ins; tests create scoped temp dirs and clean up after themselves. The count above is a layout sketch — exact totals shift as lanes ship, so `npm test` is the source of truth.
 
 ---
 

package/docs/CONTRIBUTING.md

@@ -22,7 +22,7 @@ No build step. The package is plain ESM with **zero npm runtime dependencies**.
 git clone https://github.com/sk-lim19f/Hypomnema.git
 cd Hypomnema
 npm install   # installs dev tooling only — runtime deps are zero
-npm test      # 51/51 should pass
+npm test      # all tests should pass — exact count shifts as lanes ship
 npm run lint  # frontmatter + wikilink validation
 ```
 

package/hooks/hooks.json

@@ -72,6 +72,15 @@
           }
         ]
       },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/hypo-session-record.mjs",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "hooks": [
           {

package/hooks/hypo-auto-commit.mjs

@@ -6,7 +6,8 @@
  */
 
 import { spawnSync } from 'child_process';
-import { HYPO_DIR } from './hypo-shared.mjs';
+import { HYPO_DIR, loadHypoIgnore, isIgnored } from './hypo-shared.mjs';
+import { join } from 'path';
 
 function git(...args) {
   return spawnSync('git', ['-C', HYPO_DIR, ...args], { encoding: 'utf-8', timeout: 30000 });
@@ -17,7 +18,19 @@ function hasRemote() {
   return (r.stdout || '').trim().length > 0;
 }
 
-git('add', '-A');
+// `.hypoignore` is the project privacy boundary. `git add -A` ignores it, so
+// enumerate changed paths, drop ignored ones, then stage explicitly.
+const ignorePatterns = loadHypoIgnore(HYPO_DIR);
+const porcelain = git('status', '--porcelain', '-uall');
+const paths = [];
+for (const line of (porcelain.stdout || '').split('\n')) {
+  if (!line) continue;
+  const file = line.slice(3).replace(/^"|"$/g, '').split(' -> ').pop().trim();
+  if (!file) continue;
+  if (ignorePatterns.length > 0 && isIgnored(join(HYPO_DIR, file), HYPO_DIR, ignorePatterns)) continue;
+  paths.push(file);
+}
+if (paths.length > 0) git('add', '--', ...paths);
 const staged = git('diff', '--cached', '--name-only').stdout?.trim() || '';
 if (staged) {
   const today = new Date().toISOString().slice(0, 10);

package/hooks/hypo-auto-stage.mjs

@@ -6,7 +6,7 @@
  */
 
 import { spawnSync } from 'child_process';
-import { HYPO_DIR } from './hypo-shared.mjs';
+import { HYPO_DIR, loadHypoIgnore, isIgnored } from './hypo-shared.mjs';
 
 let input = {};
 try {
@@ -24,7 +24,10 @@ try {
 const filePath = input.tool_input?.file_path ?? '';
 
 if (filePath.startsWith(HYPO_DIR + '/') || filePath === HYPO_DIR) {
-  spawnSync('git', ['-C', HYPO_DIR, 'add', filePath], { stdio: 'ignore' });
+  const patterns = loadHypoIgnore(HYPO_DIR);
+  if (patterns.length === 0 || !isIgnored(filePath, HYPO_DIR, patterns)) {
+    spawnSync('git', ['-C', HYPO_DIR, 'add', filePath], { stdio: 'ignore' });
+  }
 }
 
 console.log(JSON.stringify({ continue: true, suppressOutput: true }));

package/hooks/hypo-hot-rebuild.mjs

@@ -10,11 +10,12 @@
  * This script manages: frontmatter, H2 structure, date fields.
  */
 
-import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
-import { HYPO_DIR } from './hypo-shared.mjs';
+import { HYPO_DIR, computeSessionGrowth, formatGrowthMetrics } from './hypo-shared.mjs';
 
-const HOT_PATH = join(HYPO_DIR, 'hot.md');
+const HOT_PATH         = join(HYPO_DIR, 'hot.md');
+const GROWTH_CACHE     = join(HYPO_DIR, '.cache', 'last-session-growth.json');
 
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -88,8 +89,18 @@ ${tableRows}
   if (canonical !== current) writeFileSync(HOT_PATH, canonical);
 }
 
-try {
-  rebuild();
-} catch {}
+function emitGrowth() {
+  if (!existsSync(HYPO_DIR)) return;
+  const stats = computeSessionGrowth(HYPO_DIR);
+  const line  = formatGrowthMetrics('stop', stats);
+  if (line) process.stderr.write(`${line}\n`);
+  try {
+    mkdirSync(join(HYPO_DIR, '.cache'), { recursive: true });
+    writeFileSync(GROWTH_CACHE, JSON.stringify({ ...stats, ts: Date.now() }));
+  } catch {}
+}
+
+try { rebuild();     } catch {}
+try { emitGrowth();  } catch {}
 
 try { console.log(JSON.stringify({ continue: true, suppressOutput: true })); } catch {}

package/hooks/hypo-session-record.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * hypo-session-record.mjs — Stop hook
+ *
+ * Appends an entry to ~/hypomnema/.cache/sessions/index.jsonl for each
+ * completed session. The index.jsonl is the **primary** source for
+ * scripts/session-audit.mjs (which falls back to ~/.claude/projects/<encoded>/
+ * if the index is empty or missing — see ADR 0019).
+ *
+ * Silent: never blocks, never emits user-visible output.
+ */
+
+import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { HYPO_DIR } from './hypo-shared.mjs';
+
+const INDEX_PATH = join(HYPO_DIR, '.cache', 'sessions', 'index.jsonl');
+
+function emitContinue() {
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+}
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => raw += chunk);
+process.stdin.on('end', () => {
+  try {
+    let payload = {};
+    try { payload = JSON.parse(raw) || {}; } catch {}
+
+    const transcriptPath = payload.transcript_path || payload.transcriptPath || null;
+    const sessionId      = payload.session_id || payload.sessionId || null;
+    if (!transcriptPath || !sessionId) {
+      // Older Claude Code (no transcript_path) — fallback path in
+      // scripts/session-audit.mjs handles this case.
+      emitContinue();
+      return;
+    }
+
+    if (!existsSync(HYPO_DIR)) { emitContinue(); return; }
+    mkdirSync(dirname(INDEX_PATH), { recursive: true });
+
+    const entry = {
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+      recorded_at: new Date().toISOString(),
+      cwd: payload.cwd || process.cwd(),
+    };
+    appendFileSync(INDEX_PATH, JSON.stringify(entry) + '\n');
+  } catch {
+    // Audit is best-effort observability — never let it block session close.
+  }
+  emitContinue();
+});

package/hooks/hypo-session-start.mjs

@@ -11,9 +11,20 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from '
 import { homedir, tmpdir } from 'os';
 import { join } from 'path';
 import { spawnSync } from 'child_process';
-import { HYPO_DIR, buildOutput, SESSION_STATE_NEXT_HEADINGS } from './hypo-shared.mjs';
+import { HYPO_DIR, buildOutput, SESSION_STATE_NEXT_HEADINGS, formatGrowthMetrics } from './hypo-shared.mjs';
 
-const PROJECTS_DIR = join(HYPO_DIR, 'projects');
+const PROJECTS_DIR  = join(HYPO_DIR, 'projects');
+const GROWTH_CACHE  = join(HYPO_DIR, '.cache', 'last-session-growth.json');
+
+function readLastGrowthLine() {
+  if (!existsSync(GROWTH_CACHE)) return '';
+  try {
+    const stats = JSON.parse(readFileSync(GROWTH_CACHE, 'utf-8'));
+    return formatGrowthMetrics('start', stats);
+  } catch {
+    return '';
+  }
+}
 
 function gitPull(dir) {
   if (!existsSync(join(dir, '.git'))) return;
@@ -97,6 +108,13 @@ process.stdin.on('end', () => {
     try { data = JSON.parse(raw); } catch {}
 
     gitPull(HYPO_DIR);
+    const growthLine = readLastGrowthLine();
+    // Intentional dual emit: stderr (cyan) is the human-visible nudge in the
+    // terminal; growthPrefix injects the same plain-text line into the LLM's
+    // additionalContext so model and user start the session looking at the
+    // same state. ANSI escapes are kept out of additionalContext on purpose.
+    const growthPrefix = growthLine ? `${growthLine}\n\n` : '';
+    if (growthLine) process.stderr.write(`\n\x1b[36m${growthLine}\x1b[0m\n`);
     const cwd = data.cwd || data.directory || process.cwd();
     const sessionId = data.session_id || 'default';
     const MARKER_FILE = join(tmpdir(), `hypo-session-marker-${sessionId}.json`);
@@ -113,26 +131,30 @@ process.stdin.on('end', () => {
         if (hotContent)   parts.push(`[HOT]\n${hotContent}`);
         if (stateContent) parts.push(`[SESSION STATE — 다음 작업]\n${stateContent}`);
         console.log(JSON.stringify(
-          buildOutput(`[WIKI HOT CACHE: project=${hit.proj}]\n\n${parts.join('\n\n')}`, { continue: true, suppressOutput: true })
+          buildOutput(`${growthPrefix}[WIKI HOT CACHE: project=${hit.proj}]\n\n${parts.join('\n\n')}`, { continue: true, suppressOutput: true })
         ));
       } else {
         process.stderr.write(`\n\x1b[36m[Hypomnema]\x1b[0m project: \x1b[1m${hit.proj}\x1b[0m (no snapshot yet)\n\n`);
         writeFileSync(MARKER_FILE, JSON.stringify({ proj: hit.proj, hotPath: null, ts: Date.now() }));
         console.log(JSON.stringify(
-          buildOutput(`[WIKI HOT CACHE: project=${hit.proj}, no snapshot yet]`, { continue: true, suppressOutput: true })
+          buildOutput(`${growthPrefix}[WIKI HOT CACHE: project=${hit.proj}, no snapshot yet]`, { continue: true, suppressOutput: true })
         ));
       }
       return;
     }
 
     if (!existsSync(GLOBAL_HOT)) {
-      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      if (growthLine) {
+        console.log(JSON.stringify(buildOutput(growthLine, { continue: true, suppressOutput: true })));
+      } else {
+        console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      }
       return;
     }
 
     const globalContent = readFileSync(GLOBAL_HOT, 'utf-8').slice(0, HOT_CHARS);
     console.log(JSON.stringify(
-      buildOutput(`[WIKI HOT CACHE: global — no project matched cwd=${cwd}]\n\n${globalContent}`, { continue: true, suppressOutput: true })
+      buildOutput(`${growthPrefix}[WIKI HOT CACHE: global — no project matched cwd=${cwd}]\n\n${globalContent}`, { continue: true, suppressOutput: true })
     ));
 
   } catch {

package/hooks/hypo-shared.mjs

@@ -160,6 +160,102 @@ export function buildOutput(context, extra = {}) {
   return { ...extra, additionalContext: context };
 }
 
+// ── growth metrics (F2 + E4) ───────────────────────────────────────────────
+// Single formatter used by Stop (hot-rebuild) and SessionStart hooks so the
+// "[hypo] +N pages, ~M updated, K wikilinks" line stays consistent at both
+// ends of a session. See ADR-0018 / Lane B.
+
+/**
+ * Format a growth-metrics one-liner. Returns '' when all counts are 0 so
+ * callers can no-op silently.
+ *
+ * @param {'stop'|'start'} mode
+ * @param {{addedPages?:number, updatedPages?:number, newWikilinks?:number}} stats
+ * @returns {string}
+ */
+export function formatGrowthMetrics(mode, stats) {
+  const a = Number(stats?.addedPages)   || 0;
+  const u = Number(stats?.updatedPages) || 0;
+  const w = Number(stats?.newWikilinks) || 0;
+  if (a === 0 && u === 0 && w === 0) return '';
+  const body = `+${a} pages, ~${u} updated, ${w} wikilinks`;
+  if (mode === 'stop')  return `[hypo] ${body}`;
+  if (mode === 'start') return `[hypo] 직전 세션: ${body}. 이어서 볼까요?`;
+  return '';
+}
+
+/**
+ * Compute session growth by inspecting the wiki repo's working tree against
+ * HEAD. Counts every modified/added/untracked markdown file under `pages/`
+ * or `projects/` and totals net-new `[[wikilink]]` occurrences in the diff.
+ *
+ * @param {string} hypoDir
+ * @returns {{addedPages:number, updatedPages:number, newWikilinks:number}}
+ */
+export function computeSessionGrowth(hypoDir) {
+  const empty = { addedPages: 0, updatedPages: 0, newWikilinks: 0 };
+  if (!existsSync(join(hypoDir, '.git'))) return empty;
+  try {
+    // Single `git status --porcelain` enumerates tracked + untracked. On a
+    // clean tree (no .md changes at all) we return early and skip the much
+    // more expensive `git diff HEAD --unified=0` — Stop hook P95 win.
+    // `-uall` expands untracked directories so a brand-new `pages/new.md`
+    // isn't hidden behind a single `?? pages/` line.
+    const porcelain = spawnSync('git', ['-C', hypoDir, 'status', '--porcelain', '-uall'], { encoding: 'utf-8', timeout: 5000 });
+    if (porcelain.status !== 0) return empty;
+    let addedPages = 0, updatedPages = 0;
+    let hasTrackedMdChange = false;
+    const untrackedMd = [];
+    // Growth metrics describe wiki page activity, so restrict to the two
+    // page-bearing trees. Top-level files like README.md or root hot.md are
+    // intentionally excluded — they're scaffolding, not page growth.
+    const inPagesScope = (file) =>
+      file.endsWith('.md') && (file.startsWith('pages/') || file.startsWith('projects/'));
+    for (const line of (porcelain.stdout || '').split('\n')) {
+      if (!line) continue;
+      const xy   = line.slice(0, 2);
+      const file = line.slice(3).replace(/^"|"$/g, '').split(' -> ').pop().trim();
+      if (!inPagesScope(file)) continue;
+      if (xy === '??') { untrackedMd.push(file); addedPages++; continue; }
+      hasTrackedMdChange = true;
+      if (xy.includes('A')) addedPages++;
+      else if (xy.includes('M') || xy.includes('R')) updatedPages++;
+    }
+    if (!hasTrackedMdChange && untrackedMd.length === 0) return empty;
+
+    let plus = 0, minus = 0;
+    if (hasTrackedMdChange) {
+      // pathspec keeps non-Markdown / out-of-scope diffs from polluting the
+      // wikilink count. Without it, a `[[…]]` string in a script.js diff was
+      // being credited as a new wikilink.
+      const diff = spawnSync(
+        'git',
+        ['-C', hypoDir, 'diff', 'HEAD', '--unified=0', '--', 'pages/', 'projects/'],
+        { encoding: 'utf-8', timeout: 10000 }
+      );
+      if (diff.status === 0) {
+        for (const line of (diff.stdout || '').split('\n')) {
+          if (line.startsWith('+++') || line.startsWith('---')) continue;
+          const matches = line.match(/\[\[[^\]\n]+\]\]/g);
+          if (!matches) continue;
+          if (line.startsWith('+')) plus  += matches.length;
+          else if (line.startsWith('-')) minus += matches.length;
+        }
+      }
+    }
+    for (const f of untrackedMd) {
+      try {
+        const body = readFileSync(join(hypoDir, f), 'utf-8');
+        const matches = body.match(/\[\[[^\]\n]+\]\]/g);
+        if (matches) plus += matches.length;
+      } catch {}
+    }
+    return { addedPages, updatedPages, newWikilinks: Math.max(0, plus - minus) };
+  } catch {
+    return empty;
+  }
+}
+
 // ── .hypoignore support ────────────────────────────────────────────────────
 // Inlined here so deployed hooks (~/.claude/hooks/) don't need scripts/lib/.