hypomnema 1.2.1 → 1.3.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.2.1",
+      "version": "1.3.0",
       "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.0",
   "description": "LLM-native personal wiki system — session-aware knowledge base for Claude Code",
   "author": {
     "name": "sk-lim19f",

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/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'),

package/hooks/hypo-session-start.mjs

@@ -37,6 +37,10 @@ import {
   computeNotice,
   markNotified,
   isOptedOut,
+  resolveCliOnPath,
+  computeSiblingNotice,
+  siblingAlreadyNotified,
+  markSiblingNotified,
 } from './version-check.mjs';
 
 // Privacy guard: refuse to read+inject .hypoignore-matched
@@ -119,6 +123,45 @@ function buildUpdateNotice() {
   }
 }
 
+/**
+ * Stale-sibling notice (ADR 0038, D3). The update-notifier above only knows
+ * whether the ACTIVE install is behind latest — it is blind to an OLDER sibling
+ * that owns the `hypomnema` bin on PATH. That sibling is the live footgun:
+ * running `hypomnema init`/`upgrade` through it downgrades the active hooks.
+ *
+ * This is the ONLY surface that reaches a user already in that state, because it
+ * runs from the (newer) active hook — `doctor` invoked via the stale CLI would
+ * run the stale doctor. fs-only (no npm/which spawn). Throttled via the cache so
+ * it nags once per (cliPath@cliVersion → activeVersion) tuple. Best-effort.
+ */
+function buildSiblingNotice() {
+  try {
+    if (isOptedOut()) return '';
+    // Active install identity = hypo-pkg.json (what init/upgrade write). This is
+    // the authoritative pkgRoot+version; ACTIVE_ROOT (~/.claude) has no package.json.
+    let active = null;
+    try {
+      active = JSON.parse(readFileSync(join(homedir(), '.claude', 'hypo-pkg.json'), 'utf-8'));
+    } catch {
+      return ''; // no active metadata → nothing to compare a sibling against
+    }
+    if (!active || !active.pkgVersion) return '';
+    const cli = resolveCliOnPath('hypomnema');
+    const notice = computeSiblingNotice(cli, {
+      pkgRoot: active.pkgRoot,
+      version: active.pkgVersion,
+    });
+    if (!notice) return '';
+    const cachePath = defaultCachePath();
+    const cache = readCache(cachePath);
+    if (siblingAlreadyNotified(cache, notice.key)) return '';
+    markSiblingNotified(cachePath, notice.key);
+    return notice.line;
+  } catch {
+    return '';
+  }
+}
+
 const PROJECTS_DIR = join(HYPO_DIR, 'projects');
 const GROWTH_CACHE = join(HYPO_DIR, '.cache', 'last-session-growth.json');
 
@@ -170,7 +213,7 @@ function gitPull(dir) {
 
 /**
  * fix #10: surface unresolved sync failures recorded by a prior session's
- * Stop hook (#9). The entry is cleared only once this session's pull has
+ * Stop hook (fix #9). The entry is cleared only once this session's pull has
  * succeeded AND there is no unpushed commit left behind by a failed push
  * (`[ahead N]`).
  *
@@ -289,23 +332,27 @@ process.stdin.on('end', () => {
     const pullOk = gitPull(HYPO_DIR);
     const syncLine = syncStateNotice(pullOk);
     const growthLine = readLastGrowthLine();
-    // fix #25 PR-A2 (ADR 0022 amendment): on source='clear', surface the dying
+    // ADR 0022 amendment: on source='clear', surface the dying
     // session's identity that hypo-session-end stashed so Claude can recover
     // session-close work that /clear skipped. One-shot: marker is unlinked
     // immediately after read.
     const clearRecoveryLine = buildClearRecoveryLine(data.source);
     const updateLine = buildUpdateNotice();
+    const siblingLine = buildSiblingNotice();
     // Intentional dual emit: stderr (yellow/cyan) is the human-visible nudge in
     // the terminal; noticePrefix injects the same plain-text lines into the
     // LLM's additionalContext so model and user start the session looking at
     // the same state. ANSI escapes are kept out of additionalContext on purpose.
-    const notices = [syncLine, growthLine, clearRecoveryLine, updateLine].filter(Boolean);
+    const notices = [syncLine, growthLine, clearRecoveryLine, updateLine, siblingLine].filter(
+      Boolean,
+    );
     let noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
     if (syncLine) process.stderr.write(`\n\x1b[33m${syncLine}\x1b[0m\n`);
     if (growthLine) process.stderr.write(`\n\x1b[36m${growthLine}\x1b[0m\n`);
     if (clearRecoveryLine)
       process.stderr.write(`\n\x1b[33m${clearRecoveryLine.split('\n')[0]}\x1b[0m\n`);
     if (updateLine) process.stderr.write(`\n\x1b[33m${updateLine}\x1b[0m\n`);
+    if (siblingLine) process.stderr.write(`\n\x1b[33m${siblingLine}\x1b[0m\n`);
     const cwd = data.cwd || data.directory || process.cwd();
     const sessionId = data.session_id || 'default';
     const MARKER_FILE = sessionMarkerPath(sessionId);
@@ -389,7 +436,7 @@ process.stdin.on('end', () => {
     if (!globalContent) {
       // GLOBAL_HOT exists but is empty or .hypoignore'd — still surface any
       // pending notices (sync state, growth, AND the auto-project offer), which
-      // would otherwise be silently dropped here (codex review 2026-05-22).
+      // would otherwise be silently dropped here.
       const notice = notices.join('\n\n');
       if (notice) {
         console.log(JSON.stringify(buildOutput(notice, { continue: true, suppressOutput: true })));