hypomnema 1.8.1 → 1.8.2

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to Hypomnema are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.2] - 2026-09-10
+
+### Bug Fixes
+
+#### English
+
+- Hook notices reach the model again. They were emitted with a top-level `additionalContext`, which Claude Code silently ignores, so the close gate, the resume contract, and lookup results never arrived. Measured after the fix: a canary planted in a project's `hot.md` came back verbatim from a session with every file tool blocked, and the same canary read as absent on the previous build. ([#287](https://github.com/sk-lim19f/Hypomnema/pull/287))
+- The session-close gate reads a background-task notification the same way on every delivery path, so a task finishing after you asked to close no longer cancels the close. A refusal also reports `gateReason`, naming which check refused. ([#289](https://github.com/sk-lim19f/Hypomnema/pull/289))
+- `lint`, `verify`, `graph`, `query` and `crystallize` exit 2 on an unrecognised flag or an empty `--hypo-dir=`, instead of silently dropping it and falling back to the default vault. Their command docs no longer print placeholder syntax as runnable arguments. ([#286](https://github.com/sk-lim19f/Hypomnema/pull/286))
+- The `/compact` and `/clear` notice no longer orders a session close, no longer fires on another project's uncommitted files, and no longer goes silent when the vault is broken enough to be worth reporting (`decisions/0101`). ([#285](https://github.com/sk-lim19f/Hypomnema/pull/285))
+- `/hypo:doctor` no longer accepts a session-closed marker as proof for a project the close gate never evaluated. The marker records the set the gate actually checked, and the audit requires an artifact's project to be in that set as well as in the marker's attribution. ([#284](https://github.com/sk-lim19f/Hypomnema/pull/284))
+
+#### 한국어
+
+- 훅 알림이 다시 모델에 닿습니다. 최상단 `additionalContext`로 나가고 있었는데 Claude Code가 그것을 조용히 무시해서 close 게이트, 세션 재개 계약, lookup 결과가 도착한 적이 없었습니다. 고친 뒤 실측했습니다. 프로젝트 `hot.md`에 심은 난수를 파일 도구를 전부 막은 세션이 그대로 답했고, 같은 난수를 이전 빌드는 못 읽었습니다. ([#287](https://github.com/sk-lim19f/Hypomnema/pull/287))
+- 세션 마무리 게이트가 background task 알림을 어느 전달 경로로 오든 같게 읽습니다. 마무리를 요청한 뒤 작업이 끝나도 그 마무리가 취소되지 않습니다. 거절할 때는 `gateReason`으로 어느 검사가 거절했는지도 함께 알립니다. ([#289](https://github.com/sk-lim19f/Hypomnema/pull/289))
+- `lint`·`verify`·`graph`·`query`·`crystallize`가 못 알아보는 플래그와 빈 `--hypo-dir=`를 조용히 버리고 기본 볼트로 가는 대신 exit 2를 냅니다. 명령 문서도 placeholder 문법을 실행 가능한 인자처럼 찍지 않습니다. ([#286](https://github.com/sk-lim19f/Hypomnema/pull/286))
+- `/compact`·`/clear` 알림이 세션 마무리를 지시하지 않고, 다른 프로젝트의 미커밋 파일로 뜨지 않으며, 보고할 값어치가 있을 만큼 볼트가 망가졌을 때 조용해지지 않습니다 (`decisions/0101`). ([#285](https://github.com/sk-lim19f/Hypomnema/pull/285))
+- `/hypo:doctor`가 close 게이트가 한 번도 평가하지 않은 프로젝트에 대해 session-closed 마커를 증거로 받지 않습니다. 마커가 게이트의 실제 검사 집합을 기록하고, 감사가 산출물의 프로젝트를 귀속뿐 아니라 그 집합에서도 요구합니다. ([#284](https://github.com/sk-lim19f/Hypomnema/pull/284))
+
+### Chores
+
+#### English
+
+- The shipped `SCHEMA.md` template defines `updated` as the day content changed, not the day the file was written, and states plainly that nothing enforces it. ([#288](https://github.com/sk-lim19f/Hypomnema/pull/288))
+
+#### 한국어
+
+- 출하되는 `SCHEMA.md` 템플릿이 `updated`를 파일을 쓴 날이 아니라 내용이 바뀐 날로 정의하고, 그것을 집행하는 장치가 없다는 사실도 함께 적습니다. ([#288](https://github.com/sk-lim19f/Hypomnema/pull/288))
+
 ## [1.8.1] - 2026-09-07
 
 ### Bug Fixes

package/README.ko.md

@@ -253,11 +253,11 @@ Hypomnema는 청크가 아니라 페이지를 지식 단위로 봅니다. 새
 |---|---|---|
 | `hypo-close-guard.mjs` | `PreToolUse` | Write/Edit/MultiEdit가 세션 마무리 쓰기로 보이는데 트랜스크립트에 사용자의 마무리 신호가 없으면, 파일이 바뀌기 전에 확인을 받음 |
 | `hypo-session-start.mjs` | `SessionStart` | `hot.md` / `session-state.md` 주입 + `git pull --ff-only` |
-| `hypo-first-prompt.mjs` | `UserPromptSubmit` | 마커 기반 일회성 `hot.md` 주입 (10분 TTL) |
+| `hypo-first-prompt.mjs` | `UserPromptSubmit` | 마커 기반으로 첫 프롬프트에 재개 한 줄을 요구한다(10분 TTL). `hot.md`를 다시 읽지는 않는다 |
 | `hypo-lookup.mjs` | `UserPromptSubmit` | BM25 top-3 HIT 주입 / MISS면 가까운 슬러그 신호 |
-| `hypo-compact-guard.mjs` | `UserPromptSubmit` | 채팅에 입력된 `/compact`나 `/clear`를 감지해 컨텍스트가 지워지기 전에 session-close 체크리스트를 강제 |
-| `hypo-cwd-change.mjs` | `CwdChanged` | cwd에 맞는 프로젝트 `hot.md` 주입 |
-| `hypo-file-watch.mjs` | `FileChanged` | 위키 파일 변경 알림 (`.hypoignore` 준수. 매칭 경로는 LLM 컨텍스트로 다시 주입하지 않음) |
+| `hypo-compact-guard.mjs` | `UserPromptSubmit` | 채팅에 입력된 `/compact`나 `/clear`를 감지해 마무리가 덜 됐으면 알린다. compact 자체는 막지 않는다 |
+| `hypo-cwd-change.mjs` | `CwdChanged` | cwd에 맞는 프로젝트 `hot.md`로 컨텍스트를 만든다. `CwdChanged`에는 Claude Code가 모델로 전달하는 출력 필드가 없어 지금은 닿지 않는다 |
+| `hypo-file-watch.mjs` | `FileChanged` | 바뀐 위키 파일로 컨텍스트를 만든다(`.hypoignore` 준수). 이 패키지는 감시 경로를 등록하지 않아 이벤트가 발생할 계기가 없고, `FileChanged` 출력은 어차피 모델에 안 닿는다 |
 | `hypo-auto-stage.mjs` | `PostToolUse(Write/Edit/MultiEdit)` | 위키 파일 자동 stage |
 | `hypo-auto-commit.mjs` | `Stop` | 자동 commit + pull + push |
 | `hypo-hot-rebuild.mjs` | `Stop` | 루트 `hot.md` 포인터 테이블 재생성 (구조와 날짜) |
@@ -396,7 +396,7 @@ E. 멈춘 프로젝트 재개.
 
 `HYPO_SKIP_GATE=1`은 세션 중간에 사용자를 막을 수 있는 게이트가 존중합니다. `hypo-compact-guard`, `hypo-close-guard`, `hypo-auto-minimal-crystallize`, 그리고 `hypo-web-fetch-ingest`의 ingest 안내가 여기 해당합니다. `hypo-personal-check`(PreCompact)도 이 플래그를 읽지만, 이 훅은 이제 `/compact`를 막지 않으므로 플래그는 반복될 뻔한 미완성-마무리 `systemMessage`만 억제합니다. 기록할 필요 없는 가벼운 세션에 씁니다.
 
-> 모델 제공사에게 전송되는 범위: 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` 패턴을 먼저 점검하세요.
+> 모델 제공사에게 전송되는 범위: Hypomnema 훅은 위키 본문을 Claude Code의 추가 컨텍스트(`additionalContext`)에 실어 보내고, 이 내용은 프롬프트의 일부로 Claude 모델 제공사로 전송됩니다. 이 경로가 실제로 모델까지 닿는 것은 `hypo-session-start`와 `hypo-lookup`입니다. `hypo-cwd-change`와 `hypo-file-watch`는 `CwdChanged`와 `FileChanged` 이벤트에서 동작하는데, Claude Code가 이 두 이벤트에는 모델에 닿는 출력 필드를 두지 않아서, 두 훅이 만드는 `additionalContext`는 지금은 전송 전에 버려집니다. `.hypoignore`는 출력이 모델까지 닿는지와 무관하게 이 네 훅 모두와 `ingest`에서 적용됩니다. 등록하지 않은 파일은 모델에 닿는 두 훅이 그대로 전송합니다. (`hypo-auto-stage`/`hypo-auto-commit`은 git 스테이징용 훅이라 컨텍스트를 주입하지는 않지만, 스테이징 판단에도 `.hypoignore`를 참고합니다.) 비밀 정보는 위키에 두지 마시고, `HYPO_DIR` 아래에 민감한 내용을 저장하기 전에 `.hypoignore` 패턴을 먼저 점검하세요.
 
 > git sync 범위: Hypomnema는 `~/hypomnema/` 위키 자체만 git sync합니다. 단 `init` / `upgrade`는 `~/.claude/` 안의 관리 대상 영역(Hypomnema 자체 hook `~/.claude/hooks/`, 슬래시 커맨드 `~/.claude/commands/hypo/`, `settings.json` 등록)을 설치·SHA 추적하고, extensions companion sync로 위키의 `~/hypomnema/extensions/`에 둔 `agents/`·`commands/`·`hooks/`·`skills/`도 미러링합니다(직접 `init`·`upgrade --apply`·`capture`를 돌릴 때. `--codex`면 `hooks`·`commands` 부분집합만 `~/.codex/`로). 이 관리 대상 바깥에 있는 `~/.claude/` 콘텐츠는 일부러 관리하지 않습니다. 위키를 거치지 않는 기타 agent/skill, 머신 고유 `settings.local.json` 같은 일반 Claude Code 설정의 기기 간 동기화는 [chezmoi](https://www.chezmoi.io/) 같은 별도 dotfiles 매니저를 권합니다.
 

package/README.md

@@ -249,11 +249,11 @@ Nine commands cover the full capture → retrieval → consolidation cycle.
 |---|---|---|
 | `hypo-close-guard.mjs` | `PreToolUse` | When a Write/Edit/MultiEdit looks like a session-close write and the transcript carries no close signal from you, ask before it lands |
 | `hypo-session-start.mjs` | `SessionStart` | Inject `hot.md` / `session-state.md` + `git pull --ff-only` |
-| `hypo-first-prompt.mjs` | `UserPromptSubmit` | Marker-based one-shot `hot.md` injection (10-min TTL) |
+| `hypo-first-prompt.mjs` | `UserPromptSubmit` | Marker-based one-shot request for a resume line on the first prompt (10-min TTL). It does not re-read `hot.md` |
 | `hypo-lookup.mjs` | `UserPromptSubmit` | BM25 top-3 HIT inject / MISS → closest-slug signal |
-| `hypo-compact-guard.mjs` | `UserPromptSubmit` | Detect a typed `/compact` or `/clear`, and enforce the session-close checklist before context is wiped |
-| `hypo-cwd-change.mjs` | `CwdChanged` | Inject the matching project's `hot.md` |
-| `hypo-file-watch.mjs` | `FileChanged` | Notify on wiki-file changes (honors `.hypoignore`; matched paths are never re-emitted into LLM context) |
+| `hypo-compact-guard.mjs` | `UserPromptSubmit` | Detect a typed `/compact` or `/clear` and report an incomplete session close. It never blocks the compact |
+| `hypo-cwd-change.mjs` | `CwdChanged` | Build context from the matching project's `hot.md`. `CwdChanged` has no output field Claude Code forwards to the model, so this does not currently reach Claude |
+| `hypo-file-watch.mjs` | `FileChanged` | Build context for a changed wiki file (honors `.hypoignore`). Nothing in this package registers watch paths, so the event has no trigger here, and `FileChanged` output does not reach Claude either way |
 | `hypo-auto-stage.mjs` | `PostToolUse(Write/Edit/MultiEdit)` | Auto-stage wiki-file edits |
 | `hypo-auto-commit.mjs` | `Stop` | Auto commit + pull + push |
 | `hypo-hot-rebuild.mjs` | `Stop` | Rebuild the root `hot.md` pointer table (structure + dates) |
@@ -396,7 +396,7 @@ Place a `hypo-config.md` at the wiki root to make it portable across machines wi
 
 > If a session-close write finds its target changed since this session read it, Hypomnema does not overwrite it. It parks the bytes under `<wiki>/.cache/proposals/` and tells you. Review and apply them yourself: `hypomnema proposal list`, then `hypomnema proposal apply <id>` (at a terminal) or `hypomnema proposal discard <id>`. Inside a session, where there is no terminal to type at, the same approval is collected in the conversation: `hypomnema proposal challenge` prints the diffs, you type the line it gives you, and `hypomnema proposal resolve` writes exactly what you saw. There is no auto-apply.
 
-> 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`.
+> 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. That path actually reaches the model for `hypo-session-start` and `hypo-lookup`. `hypo-cwd-change` and `hypo-file-watch` fire on `CwdChanged` and `FileChanged`, two events for which Claude Code's hook output has no field that reaches the model, so the `additionalContext` those two hooks emit is currently dropped before transmission. `.hypoignore` is enforced at all four of these hooks (whether or not their output reaches the model) and at `ingest`, but any file _not_ matched by `.hypoignore` is fair game for transmission through the two hooks that do reach the model. (`hypo-auto-stage` and `hypo-auto-commit` are git-staging hooks, not injection points, and also honor `.hypoignore` for their staging decisions.) Keep secrets out of the wiki, and review `.hypoignore` patterns before storing anything sensitive under `HYPO_DIR`.
 
 > Scope of git sync: Hypomnema git-syncs only the `~/hypomnema/` wiki itself. `init` / `upgrade` do install and SHA-track a defined surface inside `~/.claude/`: Hypomnema's own hooks at `~/.claude/hooks/`, slash commands at `~/.claude/commands/hypo/`, and `settings.json` registrations. The extensions companion sync covers one more surface: whatever you put in `~/hypomnema/extensions/` (`agents/`, `commands/`, `hooks/`, `skills/`) lands in `~/.claude/`. With `--codex`, hooks and commands also go to `~/.codex/`. Anything _outside_ that defined surface in `~/.claude/` is intentionally not managed by Hypomnema. For general cross-machine sync of Claude Code config (other agents/skills not staged via the wiki, machine-specific `settings.local.json`, etc.), use a separate dotfiles manager such as [chezmoi](https://www.chezmoi.io/).
 

package/commands/crystallize.md

@@ -85,10 +85,12 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs \
   --apply-session-close \
   --payload=/tmp/hypo-session-close-<session-id>.json \
   --session-id=<current-session-id> \
-  --hypo-dir="<path>" \
   --json
 ```
 
+Add `--hypo-dir="<path>"` only when the user specified a Hypomnema directory explicitly;
+otherwise omit it and the script resolves the root itself.
+
 **`--session-id` is required for any close that carries a `--payload`.** It is not a
 switch that turns a check on; omitting it fails the check. Before a single byte is
 written or committed, the apply resolves that session's transcript and looks for
@@ -99,7 +101,7 @@ and nothing on disk, in three cases:
 |---|---|
 | `session-id-required` | No `--session-id` was passed. |
 | `transcript-unresolved` | The id resolves to no transcript under `~/.claude/projects/`. |
-| `no-user-close-signal` | The transcript exists, and the user never asked to close. |
+| `no-user-close-signal` | The transcript exists, but no close authority is in force right now. This one string collapses three different gate outcomes, and only one of them means the user never asked. Read `gateReason` (below) before deciding what to do about it. |
 
 A refusal is not a failure to route around. It means the close should not happen: ask
 the user, and re-run only after they say so.
@@ -129,6 +131,15 @@ no session id.
 | `--apply-session-close --payload=<path> --session-id=<id>` | The only apply path. Verifies close authority against that session's transcript **first**; on a refusal nothing is written. On success: per-field idempotent writes (no-op when bytes match), strict verification, lint gate, commit, and the per-session closed marker. Safe to re-run. |
 | `--apply-session-close --force` | Skips the probe early-exit. It does **not** skip the authority check, and `--payload` plus `--session-id` are still required to apply anything. |
 
+When a refusal carries `reason: 'no-user-close-signal'`, the JSON also carries
+`gateReason`, naming which of the three gate checks refused: `no-open` (the
+transcript holds no user close signal at all), `transcript-rewrite-detected`
+(the transcript changed under the gate), or `no-new-open-since-resolution` (the
+close signal predates a resolution already recorded). The collapsed `reason`
+stays the same string in all three cases, so read `gateReason` rather than
+parsing the `Gate detail:` fragment out of `error`. The field is absent for
+every other refusal.
+
 **Two lint gates run automatically, scoped to the files this close writes:**
 
 Both gates judge only the **payload files** (the 5 mandatory close files + `open-questions.md`). Lint debt this close did not author is never gated — so an unrelated broken page elsewhere cannot block your close. It is reported as a non-blocking notice, scoped to the close-target project: debt under `projects/<project>/` is listed by file in `notices[]`; debt elsewhere (other projects, shared `pages/`, root files) folds into the `otherDebtCount` integer so the same untouched-file debt does not re-list its filenames on every close (run `/hypo:lint` for the full list).
@@ -169,7 +180,12 @@ If `markerWritten: true`: ask: "Session closed. Would you like to also run knowl
 
 - `session-id-required`: you omitted `--session-id`. Pass the main conversation's id and re-run.
 - `transcript-unresolved`: the id resolved no transcript, so it is almost certainly not the main conversation's (a background-task or Agent-thread uuid, most often). Get the right one and re-run.
-- `no-user-close-signal`: the transcript is this session's, and the user never asked to close in wording the gate recognizes (e.g. "세션 마무리까지 진행해줘" falls outside the close-signal set). Re-running the same id changes nothing, because the transcript is unchanged. Confirm intent once with `AskUserQuestion`, header "세션", a single option labelled **세션 마무리** (설명: "이 세션을 마무리하고 close 마커를 기록"). If the user picks it, that answer lands in the transcript as a recognized close signal, so re-running the exact same command now applies **everything**: the writes, the commit, and the marker. If the user declines, the session stays open and nothing is written. Do NOT touch the close-signal matcher itself, and do not hand-write the files to work around the refusal.
+- `no-user-close-signal`: the transcript is this session's, but no close authority is in force. **Branch on `gateReason` before doing anything.** The three cases need three different responses, and treating them alike is what made this refusal look like it had a new cause every time it appeared.
+  - `no-open`: the user genuinely never asked to close in wording the gate recognizes (e.g. "세션 마무리까지 진행해줘" falls outside the close-signal set). Re-running the same id changes nothing, because the transcript is unchanged. Confirm intent once with `AskUserQuestion`, header "세션", a single option labelled **세션 마무리** (설명: "이 세션을 마무리하고 close 마커를 기록"). If the user picks it, that answer lands in the transcript as a recognized close signal, so re-running the exact same command now applies **everything**: the writes, the commit, and the marker. If the user declines, the session stays open and nothing is written.
+  - `no-new-open-since-resolution`: the user DID ask, and that request was already resolved by an earlier close. Asking again makes them answer a question they have already answered. Report that this session is already closed and stop; do not re-prompt.
+  - `transcript-rewrite-detected`: the transcript changed underneath the gate, so the earlier signal can no longer be attested. This is not a statement about what the user wants. Say what happened rather than asking them to repeat themselves, and let a human decide.
+
+  In all three: do NOT touch the close-signal matcher itself, and do not hand-write the files to work around the refusal.
 
 If the apply succeeded but `markerWritten: false`, do NOT say "session closed." Branch on `markerSkipReason` (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface the reason verbatim and address it (resolve the compact blocker, fix the git / disk issue) before re-running.
 
@@ -182,9 +198,14 @@ If the user says stop, end here. Otherwise continue to Step 5.
 Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` (or `/hypo:upgrade` on a plugin install) or reinstall instead of guessing the cache layout.
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs [--hypo-dir="<path>"] [--min-group=2]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs --min-group=2
 ```
 
+Add `--hypo-dir="<path>"` only when the user specified a Hypomnema directory explicitly;
+otherwise omit it.
+
+An unrecognized flag exits 2 instead of being ignored.
+
 Show the output to the user. If no candidates are found, tell them Hypomnema looks well-connected and no crystallization is needed.
 
 ---
@@ -255,10 +276,15 @@ Show what was created or modified, and offer to run `/hypo:lint` to verify all n
 `--check-session-close` (read-only strict gate, same check PreCompact runs) is still supported as a probe-only verification. Use it when you only want to verify that today's session-close is complete without applying anything:
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs --check-session-close [--hypo-dir="<path>"]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/crystallize.mjs --check-session-close
 ```
 
-It reports any file as `missing` or `stale`. For an actual close, prefer `--apply-session-close --payload=<path>` (Step 3) — it bundles freshness + lint into one gate and is the documented dogfood path. (`parseArgs` only accepts the `--payload=<path>` spelling; a space-separated `--payload <path>` is silently ignored and triggers "payload is required".)
+Add `--hypo-dir="<path>"` only when the user specified a Hypomnema directory explicitly;
+otherwise omit it.
+
+An unrecognized flag exits 2 instead of being ignored.
+
+It reports any file as `missing` or `stale`. For an actual close, prefer `--apply-session-close --payload=<path>` (Step 3): it bundles freshness and lint into one gate and is the documented dogfood path. `parseArgs` only accepts the `--payload=<path|->` spelling (a path, or `-` for stdin); a space-separated `--payload <path>` is rejected outright with exit 2, not silently dropped.
 
 Add `--project=<slug>` to scope the check to one project (close status + lint scope) when recency picks the wrong one. This is a project-scoped diagnostic only: a green scoped result (JSON `scope: "project"`) attests that slug is close-complete, **not** that `/compact` is unblocked globally.
 

package/commands/graph.md

@@ -23,12 +23,15 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 ## Step 2 — Run the graph script
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/graph.mjs \
-  [--hypo-dir="<path>"] \
-  [--format=json|mermaid|dot] \
-  [--min-edges=<n>]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/graph.mjs
 ```
 
+Add `--hypo-dir="<path>"` only when the user gave one (per Step 1). Add `--format=<fmt>`
+and `--min-edges=<n>` only with one concrete value from the Options list below, for
+example `--format=mermaid`; the defaults (`json`, `0`) apply when they are omitted.
+
+An unrecognized flag exits 2 instead of being ignored.
+
 Options:
 - `--format=json` (default) — adjacency list with in/out degree counts
 - `--format=mermaid` — Mermaid `graph TD` diagram (paste into a Markdown code block)

package/commands/lint.md

@@ -25,10 +25,17 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 ## Step 2 — Run lint
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.mjs [--hypo-dir="<path>"] [--json] [--fix]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.mjs --json
 ```
 
+Add `--hypo-dir="<path>"` only when the user gave one (per Step 1); otherwise leave it
+out and the script resolves the root itself.
+
+An unrecognized flag exits 2 instead of being ignored. Do not add `--fix` on this first
+pass; Step 4 covers when to offer it and re-run with it only after the user agrees.
+
 Options:
+- `--hypo-dir=<path>` (optional): Hypomnema root, pass only when the user specified one explicitly
 - `--json` — output results as JSON (useful for tooling)
 - `--fix` — auto-add missing `updated` field (safe repairs only; no other fields are modified)
 

package/commands/query.md

@@ -22,15 +22,17 @@ Ask the user what they want to know if it was not provided in the command invoca
 
 Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` (or `/hypo:upgrade` on a plugin install) or reinstall instead of guessing the cache layout.
 
+If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise
+omit the flag.
+
 Run full-text search:
 
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/query.mjs \
-  --q="<query terms>" \
-  [--hypo-dir="<path>"] \
-  [--limit=10]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/query.mjs --q="<query terms>" --limit=10
 ```
 
+An unrecognized flag exits 2 instead of being ignored.
+
 ---
 
 ## Step 3 — Read relevant pages

package/commands/verify.md

@@ -15,11 +15,22 @@ You are running `/hypo:verify`. Audit wiki pages for overdue or missing `verify_
 
 Bundled scripts here run via `${CLAUDE_PLUGIN_ROOT}/scripts/`. To resolve that package root: if `${CLAUDE_PLUGIN_ROOT}` is already an absolute path, use it; otherwise read `pkgRoot` from `~/.claude/hypo-pkg.json` (only when non-empty and the target script exists under it); otherwise use the `hypo@hypomnema` (or legacy `hypomnema@hypomnema`) installPath in `~/.claude/plugins/installed_plugins.json`; if none resolve, stop and tell the user to run `hypomnema upgrade --apply` (or `/hypo:upgrade` on a plugin install) or reinstall instead of guessing the cache layout.
 
+If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise
+omit the flag.
+
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/verify.mjs [--hypo-dir="<path>"] [--file=<path>]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/verify.mjs
 ```
 
+Add `--file="<path>"` only to check a single page (for example, right after editing it).
+Omitting it scans the whole vault (`pages/` and `projects/`); the script skips a `--file`
+path it cannot read rather than erroring, so passing one that does not exist reports
+"nothing to verify" instead of failing loudly.
+
+An unrecognized flag exits 2 instead of being ignored.
+
 Options:
+- `--hypo-dir=<path>` (optional): Hypomnema root, pass only when the user specified one explicitly
 - `--file=<path>` — check a single page only (useful after editing a page)
 
 ---

package/docs/ARCHITECTURE.md

@@ -128,16 +128,16 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 | Hook | Responsibility |
 |---|---|
 | `hypo-session-start` | Inject `index.md`, root `hot.md`, project `hot.md`/`session-state.md`. Run `git pull --ff-only` (silent fail on missing remote) |
-| `hypo-first-prompt` | Marker-based one-shot `hot.md` injection on first user prompt (10-min TTL) — for sessions that bypass `SessionStart` |
+| `hypo-first-prompt` | Reads the marker left by `hypo-session-start` or `hypo-cwd-change` and forces a one-line resume on the first user prompt (10-min TTL). It does not re-read or re-inject `hot.md` |
 | `hypo-lookup` | BM25 search over the wiki on every prompt. **HIT** → inject top-3 page snippets (≤2000 chars each; a page whose `verify_by_date` is overdue gets a `[STALE verify_by_date=…]` marker prepended). **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-compact-guard` | Detect `/compact` or `/clear` typed in chat and, if session close is incomplete, tell Claude so. It never blocks `/compact` |
 | `hypo-personal-check` | PreCompact detection: lint blockers, uncommitted changes, missing session-log entries surface as a `systemMessage`; `/compact` is never blocked here |
 | `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, device}` 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 |
+| `hypo-cwd-change` | When working directory changes, re-resolve the active project and build `additionalContext` with its `hot.md`; `CwdChanged` has no field Claude Code forwards to the model, so this does not currently reach Claude |
+| `hypo-file-watch` | Build `additionalContext` for a changed wiki file. Two things keep this inert: nothing in this package returns `watchPaths`, so the event has no registered trigger, and `FileChanged` output does not reach the model. The event also fires regardless of who changed the file, so it is not an external-edit signal |
 
 ### Deployment constraint
 
@@ -163,7 +163,7 @@ Scripts in `scripts/` are not deployed — they run from the package install pat
 | `hypoIsClean()` | Check git status + unpushed commits |
 | `hotMdIsClean()` | Validate `hot.md` structure |
 | `isCompactCommand(prompt)` | Detect `/compact` invocations |
-| `buildOutput(...)` | Format hook output for Claude Code's `additionalContext` channel |
+| `buildOutput(hookEventName, context, extra)` | Build hook output that nests `additionalContext` under `hookSpecificOutput`, keeping control fields as top-level siblings. The event name is required: Claude Code drops a payload whose `hookEventName` does not match the firing event |
 | `SESSION_STATE_NEXT_HEADINGS` | Allowed headings for "next tasks" — `## 다음 이어받기` / `## 다음 작업`. Lint reuses this constant (DRY) |
 
 ---
@@ -298,7 +298,7 @@ SessionStart
   ├─► UserPromptSubmit (every prompt)
   │     ├─► hypo-first-prompt.mjs (one-shot, 10min TTL)
   │     ├─► hypo-lookup.mjs (BM25 inject)
-  │     └─► hypo-compact-guard.mjs (block /compact when checklist incomplete)
+  │     └─► hypo-compact-guard.mjs (report incomplete checklist; never blocks /compact)
   │
   ├─► PostToolUse(Write/Edit)
   │     └─► hypo-auto-stage.mjs (git add)
@@ -307,7 +307,7 @@ SessionStart
   │     └─► hypo-personal-check.mjs (lint + session-close gate)
   │
   ├─► CwdChanged
-  │     └─► hypo-cwd-change.mjs (re-inject project hot.md)
+  │     └─► hypo-cwd-change.mjs (builds hot.md context; does not currently reach Claude)
   │
   └─► Stop
         ├─► hypo-hot-rebuild.mjs (regenerate root hot.md + growth cache)

package/docs/CONTRIBUTING.md

@@ -129,6 +129,8 @@ Everything else belongs in `commands/`, which loads the same way.
 npm test           # tests/*.test.mjs, sharded across processes — unit + smoke + contract
 npm run lint       # scripts/lint.mjs — frontmatter + wikilink validation + W8 (design-history stale
                    # vs session-log) + W14 (design-history missing but session-log implies one)
+                   # + W15 (synthesis older than the newest page in its sources_consulted)
+                   # + W16 (sources_consulted names W15 could not resolve)
 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, read as a
                    # union across every tests/*.mjs. Maintainer dogfood; needs a wiki at

package/hooks/hypo-compact-guard.mjs

@@ -9,20 +9,47 @@
  * PreCompact event at all, so this hook is the only chat-side gate that can
  * prompt session-close before a context wipe.
  *
- * Behavior: if session close is incomplete → instruct Claude to run session close
- * immediately before /compact or /clear.
+ * Behavior: if session close is incomplete, tell Claude so (a description, not
+ * an instruction — session-close-scope-boundary spec §5) before /compact or
+ * /clear runs.
+ *
+ * This hook never calls precompactGateStatus: its own hooks.json timeout is
+ * 10s and the gate's lint spawn alone budgets 30s, three times over. Instead
+ * it re-checks only the cheap axes (session log, git, hot.md) directly, and
+ * narrows the git axis with the SAME project-vs-foreign path rule the gate
+ * uses (isForeignProjectFile / classifyForeignOnlyDirty in hypo-shared.mjs), so
+ * a different project's dangling close file does not fire a false alarm here
+ * either. Unlike the gate, this hook never passes transcriptTouched into that
+ * rule: parsing the transcript is exactly the evidence spec §5 excludes to
+ * stay inside the 10s budget, so only the cheap path-prefix axis runs here.
  */
 
 import {
   lastSubstantialOpIsSession,
   hypoIsClean,
+  gitDirtyFiles,
   hotMdIsClean,
   readChecklist,
   isClearCommand,
   isCompactOrClearCommand,
   isGateSkipped,
+  resolveGateProjectOverride,
+  classifyForeignOnlyDirty,
+  buildOutput,
+  HYPO_DIR,
 } from './hypo-shared.mjs';
 
+// A fixed slice of this hook's own 10s hooks.json budget (hooks.json:60),
+// shared as ONE deadline across every git spawn hypoIsClean and
+// gitDirtyFiles make below (up to four): each call re-checks the time left
+// and skips its own spawn once the shared budget is spent, so no NEW spawn
+// starts once this budget is gone. That bounds the git-spawn total, not the
+// hook's wall-clock time end to end: measured 145ms on a normal run and
+// 6273ms with a slow fsmonitor in the mix, both inside the 10s hooks.json
+// timeout, but a spawnSync child that outlives a SIGTERM has no coded upper
+// bound here.
+const GIT_DEADLINE_BUDGET_MS = 6000;
+
 let input = '';
 process.stdin.setEncoding('utf-8');
 process.stdin.on('data', (chunk) => {
@@ -40,24 +67,98 @@ process.stdin.on('end', () => {
 
     const detected = isClearCommand(prompt) ? '/clear' : '/compact';
 
-    const hasSession = lastSubstantialOpIsSession();
-    const gitStatus = hypoIsClean();
-    const hotStatus = hotMdIsClean();
+    // These two run on EVERY /compact or /clear, unlike resolveGateProjectOverride
+    // below (which only runs when gitStatus.uncommitted is already true). A
+    // throw here would reach the outermost catch on every single prompt, not
+    // just the git-dirty ones, so the exposure is wider than the resolveGate
+    // case: fail closed locally instead ("reason present"), never fail open
+    // ("looks clean"). A read failure on either file is not the same fact as
+    // that file being genuinely absent or well-formed, so the fallback reason
+    // says "unreadable", not "missing" or "invalid", to keep the two causes
+    // tellable apart from the additionalContext text alone.
+    // lastSubstantialOpIsSession() now reads a MISSING log.md (ENOENT) as
+    // `false`, and reads only via a single readFileSync call (no separate
+    // existsSync precheck), so there is no check-then-read window where the
+    // file is deleted between the two and falls back to the old fail-open
+    // `true`. That keeps state-table row 1 (spec §5, "session log entry
+    // missing") surfaced: a brand-new vault with an all-foreign dirty tree
+    // and a clean hot.md still reports the missing log instead of going
+    // fully silent. Any OTHER read failure (EISDIR, EACCES, ...) is a real
+    // problem, so the function rethrows it, and the try/catch below turns
+    // that into the same fail-closed `hasSession = false` plus a stderr line.
+    let hasSession;
+    try {
+      hasSession = lastSubstantialOpIsSession();
+    } catch (err) {
+      process.stderr.write(
+        `[hypo-compact-guard] error: lastSubstantialOpIsSession failed, treating as session log entry missing: ${err?.message ?? String(err)}\n`,
+      );
+      hasSession = false;
+    }
+    const deadline = { end: performance.now() + GIT_DEADLINE_BUDGET_MS };
+    const gitStatus = hypoIsClean(undefined, { deadline });
+    let hotStatus;
+    try {
+      hotStatus = hotMdIsClean();
+    } catch (err) {
+      process.stderr.write(
+        `[hypo-compact-guard] error: hotMdIsClean failed, treating as hot.md unreadable: ${err?.message ?? String(err)}\n`,
+      );
+      hotStatus = { clean: false, reason: `hot.md unreadable: ${err?.message ?? String(err)}` };
+    }
 
-    // Block on uncommitted (real unsaved work); unpushed commits (ahead)
-    // are a soft, auto-synced state and must not block /compact or /clear — mirrors
-    // the precompactGateStatus demote so the chat-side gate stays consistent.
-    if (hasSession && !gitStatus.uncommitted && hotStatus.clean) {
-      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
-      return;
+    // Uncommitted (real unsaved work) blocks; unpushed commits (ahead) are a
+    // soft, auto-synced state and never reach `gitStatus.reason` here, since
+    // `uncommitted` is what gates it — mirrors the precompactGateStatus
+    // demote so the chat-side gate stays consistent.
+    let gitReason = gitStatus.uncommitted ? gitStatus.reason : '';
+    if (gitStatus.uncommitted) {
+      // resolveGateProjectOverride (session-close-scope-boundary spec §2):
+      // the same cwd-to-project resolution PreCompact and Stop already use.
+      // null just means "no project this cwd unambiguously owns" — that
+      // keeps the git axis judged globally, exactly like today. Scoped
+      // inside `uncommitted` on purpose: it only narrows the git notice, so
+      // a clean /compact has no reason to pay for a projects/ scan.
+      //
+      // Unlike classifyForeignOnlyDirty, this call is NOT contract-bound to
+      // stay silent: it walks through collectProjectWorkingDirs' own
+      // readdirSync, which sits outside that function's try/catch. Left
+      // uncaught here, that throw would escape past this hook's git-axis
+      // logic into the outermost catch and come back as a FULLY suppressed
+      // {suppressOutput:true} — silently dropping the session-log and
+      // hot.md reasons too, not just this one. Catch it locally and demote
+      // to null (its own "no project" sentinel) so a broken vault still
+      // gets every reason it is due.
+      let attributionScope = null;
+      try {
+        attributionScope = resolveGateProjectOverride(HYPO_DIR, {
+          sessionCwd: data.cwd ?? null,
+        });
+      } catch (err) {
+        process.stderr.write(
+          `[hypo-compact-guard] error: resolveGateProjectOverride failed, treating as no override: ${err?.message ?? String(err)}\n`,
+        );
+      }
+      if (attributionScope) {
+        const dirty = gitDirtyFiles(HYPO_DIR, { deadline });
+        const classification = classifyForeignOnlyDirty(HYPO_DIR, dirty, {
+          effectiveOverride: attributionScope,
+        });
+        if (classification === 'foreign-only') gitReason = '';
+      }
     }
 
     const reasons = [
       !hasSession ? 'session log entry missing' : '',
-      gitStatus.uncommitted ? gitStatus.reason : '',
+      gitReason,
       !hotStatus.clean ? hotStatus.reason : '',
     ].filter(Boolean);
 
+    if (reasons.length === 0) {
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      return;
+    }
+
     const today = new Date().toISOString().slice(0, 10);
     const checklist = readChecklist(today);
     const body = checklist
@@ -65,17 +166,19 @@ process.stdin.on('end', () => {
       : 'See hypo-guide.md for the session-close checklist.';
 
     console.log(
-      JSON.stringify({
-        continue: true,
-        additionalContext: [
-          `[WIKI_AUTOCLOSE] ${detected} detected — session close incomplete (${reasons.join(', ')}).`,
-          `Do NOT wait for user input. Run wiki session close NOW, then retry ${detected}.`,
-          ``,
-          body,
-          ``,
-          `To bypass: set HYPO_SKIP_GATE=1`,
-        ].join('\n'),
-      }),
+      JSON.stringify(
+        buildOutput(
+          'UserPromptSubmit',
+          [
+            `[WIKI_AUTOCLOSE] ${detected} detected: session close incomplete (${reasons.join(', ')}).`,
+            ``,
+            body,
+            ``,
+            `To bypass: set HYPO_SKIP_GATE=1`,
+          ].join('\n'),
+          { continue: true },
+        ),
+      ),
     );
   } catch (err) {
     // Fail-open: any parse/runtime error must not block the user's prompt.

package/hooks/hypo-cwd-change.mjs

@@ -10,7 +10,6 @@ import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
 import { join } from 'path';
 import {
   HYPO_DIR,
-  buildOutput,
   loadHypoIgnore,
   isIgnored,
   sessionMarkerPath,
@@ -153,16 +152,17 @@ process.stdin.on('end', () => {
       // working_dir distinct from the vault, surface where wiki files live.
       const vaultOrientation = buildVaultOrientation(newCwd);
       const orientPrefix = vaultOrientation ? `${vaultOrientation}\n\n` : '';
+      // Built inline rather than through buildOutput(): CwdChanged has no
+      // documented context-injection path, so the nested hookSpecificOutput
+      // shape buildOutput() now emits would be wrong for this event. The
+      // follow-up that moves this hook to systemMessage removes these three
+      // literals; until then they keep today's behaviour unchanged.
       console.log(
-        JSON.stringify(
-          buildOutput(
-            `${orientPrefix}[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
-            {
-              continue: true,
-              suppressOutput: true,
-            },
-          ),
-        ),
+        JSON.stringify({
+          continue: true,
+          suppressOutput: true,
+          additionalContext: `${orientPrefix}[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
+        }),
       );
       return;
     }
@@ -199,9 +199,11 @@ process.stdin.on('end', () => {
     if (!globalContent) {
       if (suggestPrefix) {
         console.log(
-          JSON.stringify(
-            buildOutput(suggestPrefix.trimEnd(), { continue: true, suppressOutput: true }),
-          ),
+          JSON.stringify({
+            continue: true,
+            suppressOutput: true,
+            additionalContext: suggestPrefix.trimEnd(),
+          }),
         );
       } else {
         console.log(JSON.stringify({ continue: true, suppressOutput: true }));
@@ -209,12 +211,11 @@ process.stdin.on('end', () => {
       return;
     }
     console.log(
-      JSON.stringify(
-        buildOutput(
-          `${suggestPrefix}[WIKI: cwd changed → no project match, injecting global hot]\n\n${globalContent}`,
-          { continue: true, suppressOutput: true },
-        ),
-      ),
+      JSON.stringify({
+        continue: true,
+        suppressOutput: true,
+        additionalContext: `${suggestPrefix}[WIKI: cwd changed → no project match, injecting global hot]\n\n${globalContent}`,
+      }),
     );
   } catch (err) {
     process.stderr.write(`[hypo-cwd-change] error: ${err?.message ?? String(err)}\n`);