hypomnema 1.2.1 → 1.3.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.1",
+      "version": "1.3.1",
       "homepage": "https://github.com/sk-lim19f/Hypomnema"
     }
   ]

package/.claude-plugin/plugin.json

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

package/README.ko.md

@@ -23,13 +23,15 @@ _Claude에게 기록을 맡기세요 — 그리고 그 기록이 실제로 쌓
 
 > **아래에서 자주 쓰이는 용어 간단 정리.** *프런트매터(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개를 추가했습니다:
+> **현재 자동화 범위와 다음 목표.** v1.3.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*로 부릅니다).
+>
+> **v1.3.0**은 자율성을 넓히기보다 이 레이어를 다듬습니다. 세션 마무리 흐름에 *권고형* 성찰 4가지(자동 실행 없이 제안만 — ADR 0029)가 들어가고, `hypomnema lint --strict`가 선택된 경고를 에러로 승격해 릴리스 게이트로 쓸 수 있으며, 설치가 **stale-sibling 감지**로 단단해집니다 — `$PATH`에 남은 더 오래된 `hypomnema`가 더는 활성 훅을 조용히 다운그레이드하지 못합니다(ADR 0038).
 
 ---
 
@@ -247,7 +249,7 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 
 이와 별도로 `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)를 참고하세요.
+위 네 가지 레인 외의 v1.3 세부 수정 — 세션 마무리 lint를 건드린 파일로 스코프해 무관한 debt로 `/compact`가 막히지 않게 한 변경(ADR 0037), `feedback` scope 검증기가 cwd 유래 project id를 수용하게 한 수정(OQ-34), `--strict`가 에러로 승격하는 안정적 lint 경고 ID `W1`/`W2`/`W4`(`--fix`로 자동복구되는 `W3`는 경고로 유지) — 은 [`CHANGELOG.md`](CHANGELOG.md)를 참고하세요.
 
 ### 셋업 & 유지보수
 

package/README.md

@@ -23,13 +23,15 @@ _Make Claude take notes — and measure whether it actually does._
 
 > **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:
+> **Current state vs. v2 vision.** v1.3.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.
+>
+> **v1.3.0** refines this layer rather than expanding autonomy: the session-close flow gains four *advisory* reflections (they suggest, never auto-act — ADR 0029), `hypomnema lint --strict` promotes selected warnings to errors for release gates, and install hardens with **stale-sibling detection** — an older `hypomnema` on `$PATH` can no longer silently downgrade your active hooks (ADR 0038).
 
 ---
 
@@ -247,7 +249,7 @@ All hooks resolve the wiki root via `HYPO_DIR` env → `hypo-config.md` scan →
 
 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).
+For fix-level v1.3 detail beyond the lanes above — session-close lint scoped to touched files so `/compact` is no longer blocked by unrelated debt (ADR 0037), the `feedback` scope validator accepting cwd-derived project ids (OQ-34), and the stable lint warning IDs `W1`/`W2`/`W4` that `--strict` promotes to errors (while `W3`, auto-repaired by `--fix`, stays a warning) — see [`CHANGELOG.md`](CHANGELOG.md).
 
 ### Setup & maintenance
 

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/commands/upgrade.md

@@ -28,6 +28,8 @@ node <package-root>/scripts/upgrade.mjs [--hypo-dir="<path>"]
 
 Show the output verbatim.
 
+> **Plugin installs**: if the output begins with `ℹ Plugin install detected`, the core hooks, slash commands, and `settings.json` wiring are managed by the Claude Code plugin loader — **not** by `/hypo:upgrade`. Do **not** run `--apply` expecting it to update them (it intentionally skips those to avoid double-registering every hook). To upgrade the plugin itself: `/plugin marketplace update hypomnema` then `/reload-plugins`. `--apply` in plugin mode applies vault-side migrations (SCHEMA, `.hypoignore`), refreshes package metadata, and still syncs any vault extensions — but does **not** install the core hooks/commands/settings (the plugin provides those).
+
 > **Note**: A major SCHEMA bump is only **detected** in this step. The informational `MIGRATION-vX.Y.md` file is written later by `--apply` (Step 4) and only on a major bump. `SCHEMA.md` is never auto-overwritten.
 
 ---

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.
 

package/hooks/hypo-auto-commit.mjs

@@ -43,9 +43,9 @@ if (staged) {
 }
 
 if (hasRemote()) {
-  // fix #9: pull/push failures must not stop the session, but they can no
-  // longer be swallowed silently — record each to .cache/sync-state.json so
-  // session-start (#10) and doctor (#11) can surface them next session.
+  // pull/push failures must not stop the session, but they can no longer be
+  // swallowed silently — record each to .cache/sync-state.json so session-start
+  // and doctor can surface them next session.
   const pull = git('pull', '--no-rebase', '-q');
   if (pull.status !== 0) appendSyncFailure(HYPO_DIR, 'pull', pull.stderr || pull.stdout);
   const push = git('push');

package/hooks/hypo-auto-minimal-crystallize.mjs

@@ -54,12 +54,17 @@ function emitContinue() {
   console.log(JSON.stringify({ continue: true, suppressOutput: true }));
 }
 
-function emitBlock(sessionId) {
+function emitBlock(sessionId, transcriptPath) {
   // One-line, skill-first. /hypo:crystallize is the documented session-close
   // alias; passing --session-id there writes the per-session marker that clears
   // this block. CLI fallback + bypass live in commands/crystallize.md, not here
   // — keep the Stop reason terse so the actionable instruction stands out.
-  const reason = `[WIKI_AUTOCLOSE] session-close 미완료 — /hypo:crystallize 실행으로 마무리 (session_id=${sessionId}).`;
+  // Surface the transcript path so the close can pass --transcript-path=<path>,
+  // which scopes the marker's lint gate to this session's own files (Bug A
+  // coherence: a marker written without lint would only let Stop pass for
+  // /compact to immediately re-block on the same errors).
+  const transcriptHint = transcriptPath ? ` --transcript-path=${transcriptPath}` : '';
+  const reason = `[WIKI_AUTOCLOSE] session-close 미완료 — /hypo:crystallize 실행으로 마무리 (session_id=${sessionId}${transcriptHint}).`;
   console.log(
     JSON.stringify({
       decision: 'block',
@@ -136,7 +141,7 @@ process.stdin.on('end', () => {
       return;
     }
 
-    emitBlock(sessionId);
+    emitBlock(sessionId, transcriptPath);
   } catch (err) {
     // Fail-open on any unexpected error.
     process.stderr.write(`[hypo-auto-minimal-crystallize] error: ${err?.message ?? String(err)}\n`);

package/hooks/hypo-cwd-change.mjs

@@ -99,11 +99,11 @@ process.stdin.on('end', () => {
     if (newHit) {
       const fromFile = readIfNotIgnored(newHit.hotPath, ignorePatterns);
       const content = fromFile ?? '(no hot.md yet — will be created at session close)';
-      // fix #13: arm the first-prompt marker so the NEXT user prompt re-triggers
+      // arm the first-prompt marker so the NEXT user prompt re-triggers
       // hypo-first-prompt, which forces a "Resuming <project>" summary line.
       // Only arm when real hot content was actually injected — if hot.md is
       // missing or .hypoignore'd (fromFile null), there is nothing for the LLM
-      // to summarize, so forcing "Resuming" would be empty noise (codex review).
+      // to summarize, so forcing "Resuming" would be empty noise.
       if (fromFile) {
         try {
           writeFileSync(

package/hooks/hypo-first-prompt.mjs

@@ -49,7 +49,7 @@ process.stdin.on('end', () => {
 
     const hasSnapshot = marker.hasSnapshot ?? (marker.hotPath && existsSync(marker.hotPath));
     const snapshotNote = hasSnapshot ? '' : ' (no snapshot yet — first session)';
-    // fix #13: a cwd-change re-trigger says "Resuming"; a fresh session start
+    // 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;

package/hooks/hypo-personal-check.mjs

@@ -33,6 +33,9 @@ import {
   isGateSkipped,
   isClosePattern,
   extractUserMessages,
+  extractTouchedWikiFiles,
+  closeFileTargets,
+  partitionLintScope,
 } from './hypo-shared.mjs';
 
 const WARNING_FILE = join(homedir(), '.claude', 'state', 'wiki-context-warning.json');
@@ -92,7 +95,7 @@ process.stdin.on('end', () => {
 
   const gitStatus = hypoIsClean();
   const hotStatus = hotMdIsClean();
-  // fix #17: strict session-close (steps 1~6 of the 11-step crystallize
+  // strict session-close (steps 1~6 of the 11-step crystallize
   // checklist). closeFiles gates the 5 mandatory files (steps 1-4 + log.md);
   // open-questions.md (step 5) is conditional ("변경 시") and intentionally
   // ungated — see hypo-shared.mjs sessionCloseFileStatus and spec §5.2.7.
@@ -107,6 +110,7 @@ process.stdin.on('end', () => {
   const lintPath = PKG_ROOT ? join(PKG_ROOT, 'scripts', 'lint.mjs') : null;
   let lintBlockers = [];
   let lintW8 = [];
+  let lintNotices = []; // pre-existing debt in files this session did not touch
   let lintSkipped = false;
   if (!lintPath || !existsSync(lintPath)) {
     lintSkipped = true;
@@ -118,8 +122,35 @@ process.stdin.on('end', () => {
         timeout: 30000,
       });
       const parsed = JSON.parse(r.stdout || '{}');
-      lintBlockers = parsed.errors || [];
-      lintW8 = (parsed.warns || []).filter((w) => w.id === 'W8');
+      const allErrors = parsed.errors || [];
+      const allW8 = (parsed.warns || []).filter((w) => w.id === 'W8');
+      // Bug B: judge this session on the files IT touched, not the whole vault.
+      // A readable transcript lets us scope (edited files ∪ mandatory close
+      // files); a missing/unreadable transcript falls back to the conservative
+      // global gate (never weaker than before).
+      const haveTranscript = !!(transcriptPath && existsSync(transcriptPath));
+      if (haveTranscript) {
+        const scope = new Set([
+          ...extractTouchedWikiFiles(transcriptPath, HYPO_DIR),
+          ...closeFileTargets(HYPO_DIR),
+        ]);
+        const part = partitionLintScope(allErrors, scope);
+        lintBlockers = part.blocking;
+        lintNotices = part.notice;
+        // W8 (design-history stale) is the CURRENT project's close
+        // responsibility, not cross-project debt — block on the active
+        // project's, surface others' as notices.
+        if (closeFiles.project) {
+          const mine = `projects/${closeFiles.project}/design-history.md`;
+          lintW8 = allW8.filter((w) => w.file === mine);
+          lintNotices.push(...allW8.filter((w) => w.file !== mine));
+        } else {
+          lintW8 = allW8;
+        }
+      } else {
+        lintBlockers = allErrors;
+        lintW8 = allW8;
+      }
     } catch (err) {
       /* fail-open */
       process.stderr.write(`[hypo-personal-check] error: ${err?.message ?? String(err)}\n`);
@@ -128,6 +159,16 @@ process.stdin.on('end', () => {
 
   const lintOk = lintBlockers.length === 0;
   const designHistoryOk = lintW8.length === 0;
+  // Non-blocking heads-up about pre-existing lint debt in untouched files (other
+  // projects / shared pages). Surfaced so it is visible but never blocks compact.
+  const noticeText =
+    lintNotices.length > 0
+      ? `[WIKI CHECK] ${lintNotices.length} pre-existing lint issue(s) in files this session did not touch (not blocking): ${[
+          ...new Set(lintNotices.map((b) => b.file)),
+        ]
+          .slice(0, 5)
+          .join(', ')}${lintNotices.length > 5 ? ', …' : ''} — clean up when convenient.`
+      : '';
 
   // ── fix #37 Phase C: feedback projection drift (ADR 0031) ──
   // Single blocking gate invariant (spec §7.5): integrate into THIS hook, never
@@ -169,8 +210,8 @@ process.stdin.on('end', () => {
         // ONLY when some target has a genuine, actionable issue (drift,
         // conflict, over-cap, or a malformed managed region). buildError is
         // never actionable here, so any mix that lacks a real issue fails open
-        // — including memory:clean + claude:buildError (codex review: the prior
-        // `every(buildError)` predicate wrongly blocked that case). Mirrors
+        // — including memory:clean + claude:buildError, where the prior
+        // `every(buildError)` predicate wrongly blocked that case. Mirrors
         // doctor's buildError→warn (non-fatal) handling.
         let report = null;
         try {
@@ -210,7 +251,13 @@ process.stdin.on('end', () => {
     closeFiles.ok &&
     feedbackOk
   ) {
-    console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+    console.log(
+      JSON.stringify(
+        noticeText
+          ? { continue: true, systemMessage: noticeText }
+          : { continue: true, suppressOutput: true },
+      ),
+    );
     return;
   }
 
@@ -267,7 +314,9 @@ process.stdin.on('end', () => {
       `  [ ] 9. hot.md    — update projects/<name>/hot.md (no exceptions)`,
       `  [ ] 10. root hot.md — update ~/hypomnema/hot.md active project table`,
       `  [ ] 11. updated: field — verify today's date on all touched .md files`,
-      `  [ ] 12. git commit & push`,
+      `  [ ] 12. lint — run scripts/lint.mjs; fix errors in files YOU touched`,
+      `           (other projects' / shared-page debt is reported as non-blocking notice)`,
+      `  [ ] 13. git commit & push`,
     ].join('\n');
 
   const closeIntentNote = hasCloseIntent
@@ -282,6 +331,7 @@ process.stdin.on('end', () => {
         `Run the checklist below in order, then retry /compact:`,
         ``,
         checklistText,
+        ...(noticeText ? ['', noticeText] : []),
         ``,
         `Trivial session? Bypass with HYPO_SKIP_GATE=1`,
       ].join('\n'),