hypomnema 1.0.1 → 1.2.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.2.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.2.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) | 낮음 | 높음 | 중간 | 높음 | 중간 |
 
@@ -177,7 +180,7 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 |---|---|---|
 | `/hypo:ingest` | 원본을 `sources/`에 보관하고 Claude가 `pages/`에 구조화된 페이지를 합성. 셸 헬퍼(`scripts/ingest.mjs`)는 read-only — 아직 ingest되지 않은 소스를 *목록만* 출력 | 보관할 가치가 있는 글을 읽었을 때 |
 | `/hypo:query` | BM25 검색 + LLM 합성 + `[[wikilink]]` 인용 | 자기 노트에 근거한 답변이 필요할 때 |
-| `/hypo:crystallize` | 초안 합성 + 11단계 session-close 체크리스트 | 비자명한 세션 종료 시 |
+| `/hypo:crystallize` | session-close 체크리스트(steps 1~6) + 요청 시 초안 합성(steps 7~11) | 비자명한 세션 종료 시 |
 | `/hypo:resume` | 활성 프로젝트의 가장 최근 세션 상태 로드 | 일시 중단된 프로젝트로 돌아올 때 |
 | `/hypo:feedback` | AI 행동 교정 기록, 영구 규칙으로 승격 가능 | Claude가 잘못 하거나 정확히 잘 했을 때 |
 | `/hypo:verify` | `verify_by` frontmatter 페이지 감사 | 시간 제약 지식이 노후화됐을 가능성이 있을 때 |
@@ -193,7 +196,7 @@ v1.0에서는 `personal / shared / public` 3-mode를 만들었습니다. 현실
 | `hypo-lookup.mjs` | `UserPromptSubmit` | BM25 top-3 HIT 주입 / MISS → 가까운 슬러그 신호 |
 | `hypo-compact-guard.mjs` | `UserPromptSubmit` | `/compact` 감지 → session-close 체크리스트 강제 |
 | `hypo-cwd-change.mjs` | `CwdChanged` | cwd에 매칭되는 프로젝트 `hot.md` 주입 |
-| `hypo-file-watch.mjs` | `FileChanged` | 위키 파일 변경 알림 |
+| `hypo-file-watch.mjs` | `FileChanged` | 위키 파일 변경 알림 (`.hypoignore` 준수 — 매칭 경로는 LLM 컨텍스트로 재주입되지 않음) |
 | `hypo-auto-stage.mjs` | `PostToolUse(Write/Edit)` | 위키 파일 자동 stage |
 | `hypo-auto-commit.mjs` | `Stop` | 자동 commit + pull + push |
 | `hypo-hot-rebuild.mjs` | `Stop` | `hot.md` 재생성 |
@@ -295,6 +298,10 @@ Claude가 잘못하거나 정확히 맞았을 때마다 `/hypo:feedback`을 실
 
 `.hypoignore`는 훅이 무시할 경로를 정의합니다 (기본: `*.pdf`, `*.zip`, `*.pem`, `*.env` 등). 직접 편집하면 됩니다 — privacy mode 플래그는 없습니다. 단일 파일, 단일 진실 소스.
 
+> **Provider 전송 디스클레이머.** Hypomnema 훅은 위키 콘텐츠를 Claude Code의 `additionalContext`로 emit하며, 이는 프롬프트의 일부로 Claude 모델 provider에 전송됩니다. `.hypoignore`는 모든 콘텐츠 주입 훅(`hypo-file-watch`, `hypo-session-start`, `hypo-cwd-change`, `hypo-lookup`) 및 `ingest`에서 강제되지만, `.hypoignore`에 매칭되지 *않는* 파일은 전송 대상입니다. (`hypo-auto-stage`/`hypo-auto-commit`은 git staging 훅이며 주입 지점이 아니지만, staging 판단에도 `.hypoignore`를 준수합니다.) 위키에 비밀을 두지 말고, `HYPO_DIR` 아래 민감 콘텐츠를 저장하기 전 `.hypoignore` 패턴을 검토하세요.
+
+> **git sync 범위.** Hypomnema는 `~/hypomnema/` 위키 자체만 git sync합니다. Claude Code 설정(`~/.claude/`)은 의도적으로 Hypomnema가 **관리하지 않습니다** — agent·skill·settings의 기기 간 동기화는 [chezmoi](https://www.chezmoi.io/) 같은 별도 dotfiles 매니저 사용을 권장합니다.
+
 ### `/hypo:*` 커맨드는 어디서 오는가?
 
 | 설치 경로 | 슬래시 커맨드 위치 |
@@ -315,7 +322,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 |
 
@@ -177,7 +180,7 @@ Eight commands cover the full capture → retrieval → consolidation cycle.
 |---|---|---|
 | `/hypo:ingest` | Saves the raw source under `sources/`; Claude synthesizes a structured page under `pages/`. The shell helper (`scripts/ingest.mjs`) is read-only — it only *lists* pending sources so you know what still needs ingesting | Anytime you read something worth keeping |
 | `/hypo:query` | BM25 retrieval + LLM synthesis with `[[wikilink]]` citations | When you need an answer grounded in your own notes |
-| `/hypo:crystallize` | Synthesizes drafts and runs the 11-step session-close checklist | End of a non-trivial session |
+| `/hypo:crystallize` | Runs the session-close checklist (steps 1~6) and, on request, synthesizes drafts (steps 7~11) | End of a non-trivial session |
 | `/hypo:resume` | Loads the most recent session state for an active project | Coming back to a paused project |
 | `/hypo:feedback` | Records an AI behavior correction; eligible for promotion to permanent rules | Right when Claude does something wrong (or exactly right) |
 | `/hypo:verify` | Audits pages with `verify_by` frontmatter | When time-bound knowledge might have aged out |
@@ -193,7 +196,7 @@ Eight commands cover the full capture → retrieval → consolidation cycle.
 | `hypo-lookup.mjs` | `UserPromptSubmit` | BM25 top-3 HIT inject / MISS → closest-slug signal |
 | `hypo-compact-guard.mjs` | `UserPromptSubmit` | Detect `/compact` → enforce session-close checklist |
 | `hypo-cwd-change.mjs` | `CwdChanged` | Inject the matching project's `hot.md` |
-| `hypo-file-watch.mjs` | `FileChanged` | Notify on wiki-file changes |
+| `hypo-file-watch.mjs` | `FileChanged` | Notify on wiki-file changes (honors `.hypoignore` — matched paths are never re-emitted into LLM context) |
 | `hypo-auto-stage.mjs` | `PostToolUse(Write/Edit)` | Auto-stage wiki-file edits |
 | `hypo-auto-commit.mjs` | `Stop` | Auto commit + pull + push |
 | `hypo-hot-rebuild.mjs` | `Stop` | Rebuild `hot.md` |
@@ -295,6 +298,10 @@ 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.
 
+> **Provider transmission disclaimer.** Hypomnema hooks emit wiki content into Claude Code's `additionalContext`, which is transmitted to the Claude model provider as part of the prompt. `.hypoignore` is enforced at every content-injection hook (`hypo-file-watch`, `hypo-session-start`, `hypo-cwd-change`, `hypo-lookup`) and at `ingest`, but any file *not* matched by `.hypoignore` is fair game for transmission. (`hypo-auto-stage` and `hypo-auto-commit` are git-staging hooks, not injection points, and also honor `.hypoignore` for their staging decisions.) Keep secrets out of the wiki, and review `.hypoignore` patterns before storing anything sensitive under `HYPO_DIR`.
+
+> **Scope of git sync.** Hypomnema git-syncs only the `~/hypomnema/` wiki itself. Your Claude Code configuration (`~/.claude/`) is intentionally **not** managed by Hypomnema — for cross-machine sync of agents, skills, and settings, the recommended pattern is a separate dotfiles manager such as [chezmoi](https://www.chezmoi.io/).
+
 ### Where do `/hypo:*` commands live?
 
 | Install path | Slash commands served from |
@@ -315,7 +322,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 `journal/weekly/<YYYY-Www>.md` (spec §6.4 SoT):
+  ```bash
+  node <package-root>/scripts/weekly-report.mjs [--hypo-dir="<path>"] [--week=YYYY-Www] --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/commands/crystallize.md

@@ -4,47 +4,125 @@ description: Crystallize draft notes into stable knowledge — also the session-
 
 You are running `/hypo:crystallize`. This command serves two purposes:
 
-1. **Session close** — if invoked at the end of a session, run the session-close checklist first
+1. **Session close** — if invoked at the end of a session, run the session-close mechanical-apply path
 2. **Knowledge synthesis** — consolidate draft or scattered wiki pages into stable, well-linked pages
 
 ---
 
 ## Step 1 — Detect context
 
-If the user invoked `/hypo:crystallize` to close a session (phrases like "세션 종료", "오늘 작업 마무리", "session close", or "wrap up"), run Steps 2–3 (session-close checklist) **before** the synthesis scan. Otherwise skip to Step 4.
+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.
 
 ---
 
-## Step 2 — Session-close checklist
+## Step 2 — Compose the session-close payload
 
-Work through each item in order. For an explicit session-close invocation, proceed automatically without asking for confirmation on each item.
+The session-close path is **payload-driven** (fix #38). Instead of writing the 5 mandatory files one-by-one, you compose a single JSON payload that describes the full session-close state, then hand it to `crystallize.mjs --apply-session-close`, which performs idempotent atomic writes and gates the result with lint.
 
-1. **session-state.md** — update `projects/<name>/session-state.md` with the next tasks list for the upcoming session (what to tackle first next time).
-2. **hot.md (project)** — update `projects/<name>/hot.md` with a session snapshot: what changed and decisions made. Keep under 500 words. Do not put next-step tasks here; those belong in session-state.md.
-3. **hot.md (root)** — update `<hypo-root>/hot.md` active-projects pointer table: set the `Last Session` date for this project to today.
-4. **session-log** — append a session entry to `projects/<name>/session-log/YYYY-MM.md` (create the file if it does not exist for this month).
-5. **open-questions** — only if `pages/open-questions.md` exists and questions were raised or resolved this session: move resolved ones out; add newly raised ones. Skip if unchanged.
-6. **log.md** — append a `session` entry to `<hypo-root>/log.md`.
+Payload shape (5 required + 1 conditional, per Spec §5.2.7 / §8.3 + ADR 0029):
+
+```json
+{
+  "project": "<project-name>",
+  "date": "YYYY-MM-DD",
+  "sessionState": { "content": "<full body of projects/<name>/session-state.md>" },
+  "projectHot": { "content": "<full body of projects/<name>/hot.md>" },
+  "rootHot": { "content": "<full body of <hypo-root>/hot.md>" },
+  "sessionLog": { "entry": "<entry to append to projects/<name>/session-log/YYYY-MM.md>" },
+  "log": { "entry": "<entry to append to <hypo-root>/log.md>" },
+  "openQuestions": { "content": "<full body of pages/open-questions.md>" }
+}
+```
+
+> **Important:** the JSON above is a literal template — do not add `//` or `#` comments when materializing it. `readPayload()` runs `JSON.parse`, which rejects comments and would fail the apply before any write.
+
+Field rules:
+
+- `project` — optional. Falls back to the active project from root `hot.md` pointer table.
+- `date` — optional. Defaults to today (local). Must be `YYYY-MM-DD` if supplied.
+- `openQuestions` — optional. Include only when `pages/open-questions.md` exists and changed this session.
+- All other top-level fields are required.
+
+Notes:
+
+- `sessionState` / `projectHot` / `rootHot` / `openQuestions` are **overwrite** (full-file content). `sessionLog` / `log` are **append** (entry-level idempotency — exact-entry dedup, safe to re-run).
+- Frontmatter `updated:` is NOT auto-fixed. If your payload's `updated:` is stale, the post-apply verification gate will fail with `stage='post-apply-verification'` and you must fix the payload and retry.
+- Write the payload to a temp path, e.g. `/tmp/hypo-session-close-<YYYY-MM-DD>.json`.
+
+Content guidance for each slot:
+
+1. **sessionState** — next tasks list for the upcoming session (what to tackle first next time).
+2. **projectHot** — session snapshot under 500 words: what changed and decisions made. Do **not** put next-step tasks here; those belong in `sessionState`.
+3. **rootHot** — active-projects pointer table with this project's `Last Session` date set to today.
+4. **sessionLog** — one session entry to append to `projects/<name>/session-log/YYYY-MM.md`.
+5. **log** — one `session` entry to append to `<hypo-root>/log.md`.
+6. **openQuestions** (conditional) — only if `pages/open-questions.md` exists and questions were raised or resolved this session.
+
+---
+
+## Step 3 — Apply the payload
+
+```bash
+node <package-root>/scripts/crystallize.mjs \
+  --apply-session-close \
+  --payload=/tmp/hypo-session-close-<YYYY-MM-DD>.json \
+  --session-id=<current-session-id> \
+  --hypo-dir="<path>" \
+  --json
+```
+
+**`--session-id` (fix #27 PR-C):** pass the current session's id whenever you
+know it — most importantly when this close was triggered by a `[WIKI_AUTOCLOSE]`
+Stop-hook block (the block reason prints the exact `--session-id` to use). On a
+verified close (`ok: true` + clean git tree), it writes the per-session marker
+`HYPO_DIR/.cache/session-closed-<id>.marker`. That marker is what tells the
+Stop-chain Layer 3 hook (`hypo-auto-minimal-crystallize`) the session is closed,
+so it stops re-prompting. Omit it only when running crystallize purely for
+synthesis (no session-close intent) — the marker is then simply not written.
+
+**Behavior (fix #39 option D + fix #40 lint gates):**
+
+| Invocation | Behavior |
+|---|---|
+| `--apply-session-close` (no `--payload`) | **Probe mode** — exits 0 with "오늘 이미 close 완료로 보임" if all 5 files are fresh today; exits 1 with "payload is required" otherwise. Cheap "already complete?" check. |
+| `--apply-session-close --payload=<path>` | **Always-apply** — payload presence = explicit close intent. Per-field idempotent writes (no-op when bytes match), then strict verification + lint gate. Safe to re-run. |
+| `--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):**
+
+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).
 
 ---
 
-## Step 3 — Session-close confirmation
+## Step 4 — Stage-based recovery
+
+The result JSON includes a `stage` field when `ok: false`. Branch on it:
 
-After completing the checklist, report:
+| `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. |
+| `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-verification+lint` | Both above. | Fix both; re-run. |
 
-- ✓ session-state.md updated
-- ✓ hot.md (project + root) updated
+Once `ok: true`, report:
+
+- ✓ session-state.md applied
+- ✓ hot.md (project + root) applied
 - ✓ session-log entry appended
-- ✓ open-questions updated (or skipped if unchanged)
-- ✓ log.md updated
+- ✓ open-questions applied (or skipped if unchanged)
+- ✓ log.md entry appended
+- ✓ post-apply lint clean
 
 Then ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
 
-If the user says stop, end here. Otherwise continue to Step 4.
+If the user says stop, end here. Otherwise continue to Step 5.
 
 ---
 
-## Step 4 — Surface synthesis candidates
+## Step 5 — Surface synthesis candidates
 
 Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
 
@@ -56,7 +134,7 @@ Show the output to the user. If no candidates are found, tell them Hypomnema loo
 
 ---
 
-## Step 5 — Choose what to crystallize
+## Step 6 — Choose what to crystallize
 
 If candidates exist, ask:
 
@@ -67,7 +145,7 @@ If candidates exist, ask:
 
 ---
 
-## Step 5a — Tag cluster synthesis
+## Step 6a — Tag cluster synthesis
 
 For a tag cluster:
 
@@ -89,7 +167,7 @@ For a tag cluster:
 
 ---
 
-## Step 5b — Draft upgrade
+## Step 6b — Draft upgrade
 
 For a draft page:
 
@@ -100,7 +178,7 @@ For a draft page:
 
 ---
 
-## Step 5c — Cross-link unlinked pages
+## Step 6c — Cross-link unlinked pages
 
 For unlinked pages:
 
@@ -111,6 +189,18 @@ For unlinked pages:
 
 ---
 
-## Step 6 — Report
+## Step 7 — Report
 
 Show what was created or modified, and offer to run `/hypo:lint` to verify all new links resolve.
+
+---
+
+## Appendix — Legacy `--check-session-close`
+
+`--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 <package-root>/scripts/crystallize.mjs --check-session-close [--hypo-dir="<path>"]
+```
+
+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".)

package/commands/feedback.md

@@ -2,23 +2,34 @@
 description: Record an AI behavior correction or preference into the wiki
 ---
 
-You are running `/hypo:feedback`. Capture a behavior correction or preference into `pages/feedback/` for future sessions.
+You are running `/hypo:feedback`. Capture a behavior correction or preference into `pages/feedback/` — the **single source of truth** for learned behaviors (ADR 0031 / fix #37).
 
 ## What this does
 
-- Creates or updates `pages/feedback/<topic>.md` with a dated entry
+- Creates or updates `pages/feedback/<topic>.md` with a dated entry and full classification frontmatter
 - Appends a reference to `log.md`
-- Ensures the feedback is findable in future sessions
+- **Automatically refreshes the projection** into `MEMORY.md` and the user's CLAUDE.md `<learned_behaviors>` via `feedback-sync --write`
+
+> ⚠️ Do **not** hand-edit MEMORY.md or CLAUDE.md `<learned_behaviors>` for feedback. Those are one-way projections derived from the wiki page. Edit the wiki page; the projection follows.
 
 ---
 
 ## Step 1 — Gather feedback details
 
-If the user did not provide them, ask:
+If the user did not provide them, ask. The classification fields are required so the page can project correctly:
+
+1. **Topic** (slug): "What topic does this feedback apply to? (e.g. `response-length`, `commit-style`)"
+2. **Rule** (entry): "State the rule or correction in one or two sentences."
+3. **Reason**: "What incident or reasoning prompted this?"
+4. **Scope**: "Does this apply globally (all projects) or to this project only?" → `global` | `project:<project-id>` (project-id must exact-match the resolved id; see Step 3 note)
+5. **Tier**: "Is this a hard rule (L1) or a softer preference (L2)?" → `L1` | `L2`
+6. **Targets**: "Where should this project?" → `project-memory` (MEMORY.md) and/or `claude-learned` (global CLAUDE.md). Default `project-memory`.
+7. **Priority** (1–5, higher sorts first; default 3).
+8. **Sensitivity**: `public` (default) or `sanitized` (redacted secrets/paths). `private` is not allowed — the wiki is git-pushed.
 
-1. **Topic** (slug): "What topic does this feedback apply to? (e.g. `response-length`, `commit-style`, `code-comments`)"
-2. **Rule**: "State the rule or correction in one or two sentences."
-3. **Why** (optional): "What was the reason or incident that prompted this?"
+If **claude-learned** is among the targets, the page must be `scope: global` + `tier: L1`, and you must also collect:
+- **Global summary**: a one-line summary for the CLAUDE.md learned-behaviors entry.
+- Confirm **promote to global** (the page is only projected to CLAUDE.md when promoted).
 
 ---
 
@@ -30,38 +41,41 @@ To check for an existing topic, locate the Hypomnema package root and run:
 node <package-root>/scripts/feedback.mjs --list [--hypo-dir="<path>"]
 ```
 
-If a matching topic exists, confirm with the user whether to append to it or create a new one.
+If a matching topic exists, appending adds a dated entry and bumps `updated:` (classification frontmatter is preserved).
 
 ---
 
-## Step 3 — Write the feedback entry
-
-Compose the entry text. Format:
-
-```
-**Rule**: <one-line rule>
-
-**Why**: <reason or incident>
-
-**How to apply**: <when this kicks in>
-```
+## Step 3 — Write the feedback page
 
-Then run:
+Run with `--dry-run` first to preview the generated page, then without it to write. Pass every collected field:
 
 ```bash
 node <package-root>/scripts/feedback.mjs \
   --topic="<slug>" \
-  --entry="<formatted entry text>" \
+  --entry="<one-line rule>" \
+  --scope="global|project:<project-id>" \
+  --tier="L1|L2" \
+  --targets="project-memory[,claude-learned]" \
+  --priority=<1-5> \
+  --sensitivity="public|sanitized" \
+  --memory-summary="<one-line MEMORY.md summary>" \
+  --reason="<why this rule exists>" \
+  [--global-summary="<one-line CLAUDE.md summary>" --promote-to-global] \
+  [--source="session:<date>"] \
   [--hypo-dir="<path>"] \
   [--dry-run]
 ```
 
-Run with `--dry-run` first to preview, then without it to write.
+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 트랙에서 다룸.
+
+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`.
 
 ---
 
-## Step 4 — Confirm and cross-reference
+## Step 4 — Confirm
 
-After writing:
-- Tell the user: "Saved to `pages/feedback/<topic>.md`."
-- If this feedback should also update the project's `session-state.md` or the user's CLAUDE.md `<learned_behaviors>`, ask: "Should I also add this to your CLAUDE.md learned behaviors?"
+After writing, tell the user:
+- "Saved to `pages/feedback/<topic>.md` and refreshed the MEMORY/CLAUDE projection."
+- If the projection post-step warned (over-cap, conflict, unresolved project-id), surface that and suggest `hypomnema feedback-sync --check`.

package/commands/ingest.md

@@ -21,13 +21,33 @@ Ask the user:
 2. **Slug**: "What slug should this source have? (e.g. `openai-swarm-paper`, `team-retro-2026-04`)"
    - Default: derive from title or filename
 
-If a URL is provided, fetch the content. If a file path is provided, read it.
+Do **not** fetch the URL or read the file yet — the privacy guard in Step 2 must run first.
 
 ---
 
-## Step 2 — Check for orphaned sources
+## Step 2 — Privacy guard (`.hypoignore`)
 
-Locate the Hypomnema package root. Run the ingest helper to surface existing orphaned sources:
+Refuse to ingest secrets (`.env`, SSH keys, credentials) before they ever reach `sources/`. Locate the Hypomnema package root and run the guard for **both** the input path and the destination path:
+
+1. **If the source is a file path**, check it (use an absolute path):
+
+   ```bash
+   node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] --check="<absolute-input-path>"
+   ```
+
+2. **Always** check the destination `sources/<slug>.<ext>`:
+
+   ```bash
+   node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] --check="sources/<slug>.<ext>"
+   ```
+
+If either command exits non-zero, **stop**: surface the `Refused: ...` message to the user and do not fetch, read, or save the source. The slug check matters because a user could rename a `.env` to an innocuous slug — the destination must still be blocked.
+
+---
+
+## Step 3 — Check for orphaned sources
+
+Run the ingest helper to surface existing orphaned sources:
 
 ```bash
 node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"]
@@ -35,9 +55,11 @@ node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"]
 
 If there are orphaned sources already in `sources/`, ask: "There are N unprocessed sources — do you want to ingest one of those instead?"
 
+Once the guard has passed: if a URL is provided, fetch the content; if a file path is provided, read it.
+
 ---
 
-## Step 3 — Save raw source
+## Step 4 — Save raw source
 
 Save the raw content to `sources/<slug>.<ext>` (use `.md` for text, `.txt` for plain text, `.pdf` or original extension for documents).
 
@@ -45,13 +67,13 @@ Do **not** modify or summarize in the sources file — save it as-is.
 
 ---
 
-## Step 4 — Synthesize
+## Step 5 — Synthesize
 
 Read and synthesize the source:
 
 1. **Check index.md** — does a page on this topic already exist?
    - If yes: update the existing page (merge new information, mark `updated:` today)
-   - If no: create a new page in `pages/` with `type: source-summary` and `source: <slug>`
+   - If no: create a new page in `pages/` with `type: source-summary` and `sources: [<slug>]`
 
 2. **Frontmatter** for new pages:
    ```yaml
@@ -60,7 +82,7 @@ Read and synthesize the source:
    type: source-summary
    updated: YYYY-MM-DD
    tags: [<relevant tags>]
-   source: <slug>
+   sources: [<slug>]
    confidence: high | medium | low
    evidence_strength: direct
    ---
@@ -70,14 +92,14 @@ Read and synthesize the source:
 
 ---
 
-## Step 5 — Update index.md and log.md
+## Step 6 — Update index.md and log.md
 
 - Append a line to `index.md`: `- [[pages/<slug>]] — <one-line description>`
 - Append to `log.md`: `- YYYY-MM-DD ingest: [[pages/<slug>]] from sources/<slug>.<ext>`
 
 ---
 
-## Step 6 — Report
+## Step 7 — Report
 
 Show:
 - ✓ Saved source: `sources/<slug>.<ext>`

package/commands/upgrade.md

@@ -28,7 +28,7 @@ node <package-root>/scripts/upgrade.mjs [--hypo-dir="<path>"]
 
 Show the output verbatim.
 
-> **Note**: If a major SCHEMA bump is detected, this step generates a `MIGRATION-vX.Y.md` file in the Hypomnema root. This is a new informational file — no existing files are overwritten.
+> **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.
 
 ---
 
@@ -38,7 +38,7 @@ Show the output verbatim.
 - `⚠` — minor update available (stale hook or missing settings entry)
 - `✗` — major version bump or missing hook files (action required)
 
-For a **major SCHEMA bump**: point the user to the generated `MIGRATION-vX.Y.md` file in their Hypomnema root and ask them to review it before applying.
+For a **major SCHEMA bump**: warn the user that `--apply` will additionally write a `MIGRATION-vX.Y.md` informational file in their Hypomnema root and that they must manually merge the SCHEMA diff after applying.
 
 ---