hypomnema 1.4.2 → 1.5.1

package/commands/stats.md

@@ -15,7 +15,7 @@ You are running `/hypo:stats`. Display a summary of wiki health and activity.
 
 ## Step 1 — Run script
 
-The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
+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 reinstall instead of guessing the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
 

package/commands/uninstall.md

@@ -20,13 +20,15 @@ Say:
 
 Default: yes (dry-run first)
 
+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 reinstall instead of guessing the cache layout.
+
 ---
 
 ## Step 2 — Dry run
 
 Run:
 ```
-node scripts/uninstall.mjs
+node ${CLAUDE_PLUGIN_ROOT}/scripts/uninstall.mjs
 ```
 
 Show the output to the user. Ask:
@@ -39,7 +41,7 @@ If no → abort and confirm nothing was changed.
 ## Step 3 — Apply (if confirmed)
 
 ```
-node scripts/uninstall.mjs --apply
+node ${CLAUDE_PLUGIN_ROOT}/scripts/uninstall.mjs --apply
 ```
 
 If the user also wants Codex hooks removed, append `--codex`.

package/commands/upgrade.md

@@ -14,7 +14,7 @@ You are running `/hypo:upgrade`. Check if the installed Hypomnema wiki is out of
 
 ## Step 1 — Run script
 
-The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
+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 reinstall instead of guessing the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
 

package/commands/verify.md

@@ -13,7 +13,7 @@ You are running `/hypo:verify`. Audit wiki pages for overdue or missing `verify_
 
 ## Step 1 — Run
 
-The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
+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 reinstall instead of guessing the cache layout.
 
 ```bash
 node ${CLAUDE_PLUGIN_ROOT}/scripts/verify.mjs [--hypo-dir="<path>"] [--file=<path>]

package/docs/ARCHITECTURE.md

@@ -110,7 +110,7 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 |---|---|
 | `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-lookup` | BM25 search over the wiki on every prompt. **HIT** → inject top-3 page snippets (≤2000 chars each, with verify-by-date warnings). **MISS** → emit closest-slug signal that prompts Claude to research + `/hypo:ingest` |
+| `hypo-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-personal-check` | PreCompact validation: lint blockers, uncommitted changes, missing session-log entries → block compact |
 | `hypo-auto-stage` | After Write/Edit on a wiki path, run `git add` (skips paths matching `.hypoignore`) |
@@ -335,7 +335,7 @@ journal/weekly/<YYYY-Www>.md               ← committed report (heuristic v0, s
 
 `session-audit.mjs` reads transcripts from two locations, in priority order:
 
-1. **Primary:** `<hypo-root>/.cache/sessions/index.jsonl` — written by the Stop hook `hypo-session-record.mjs`. Each line: `{ session_id, transcript_path, recorded_at, cwd, device }`. `device` (PRAC-17) is `os.hostname()` for multi-machine audit; the index lives under `.cache/` (gitignored in a normal vault) so it is a local-only per-session record.
+1. **Primary:** `<hypo-root>/.cache/sessions/index.jsonl` — written by the Stop hook `hypo-session-record.mjs`. Each line: `{ session_id, transcript_path, recorded_at, cwd, device }`. `device` is `os.hostname()` for multi-machine audit; the index lives under `.cache/` (gitignored in a normal vault) so it is a local-only per-session record.
 2. **Fallback:** `~/.claude/projects/<encoded>/*.jsonl` — scanned when the index is missing or empty (legacy / freshly-installed wikis).
 
 ### Classification
@@ -366,7 +366,7 @@ The score is a **proxy, not ground truth**. The four-week baseline plan (capture
 
 The observability pipeline reads but never republishes raw transcripts. Weekly reports only emit `session_id` plus aggregate counts — no transcript content, no URLs, no tool inputs. Transcripts themselves live under `~/.claude/projects/` or `.cache/sessions/` which `.hypoignore` already excludes from any sync.
 
-**PRAC-17 audit fields (`device`, `session_id`).** `device` (`os.hostname()`) is recorded in two places with different sync boundaries, by design. In `.cache/sessions/index.jsonl` it is per-session-accurate but **local-only** (`.cache/` is gitignored in a normal vault). In the seeded session-log daily-shard frontmatter it is an **intentional synced field** — a creator-only stamp (the session/machine that first created the day's shard), carried across machines so the wiki itself records which machine opened each day. `session_id` (the Claude session UUID) is seeded into that same synced frontmatter, but only on the Stop-chain close path that passes `--session-id`; on manual/skill closes it is omitted. This deliberately puts a hostname (and, on the automated path, the session UUID) into git-tracked, synced content; it is acceptable for a single-user private vault where multi-machine identification is the goal. Operators who do not want a hostname synced can override `os.hostname()` at the OS level or treat the field as a pseudonymous label.
+**Audit fields (`device`, `session_id`).** `device` (`os.hostname()`) is recorded in two places with different sync boundaries, by design. In `.cache/sessions/index.jsonl` it is per-session-accurate but **local-only** (`.cache/` is gitignored in a normal vault). In the seeded session-log daily-shard frontmatter it is an **intentional synced field** — a creator-only stamp (the session/machine that first created the day's shard), carried across machines so the wiki itself records which machine opened each day. `session_id` (the Claude session UUID) is seeded into that same synced frontmatter, but only on the Stop-chain close path that passes `--session-id`; on manual/skill closes it is omitted. This deliberately puts a hostname (and, on the automated path, the session UUID) into git-tracked, synced content; it is acceptable for a single-user private vault where multi-machine identification is the goal. Operators who do not want a hostname synced can override `os.hostname()` at the OS level or treat the field as a pseudonymous label.
 
 ### Growth metrics (Lane B)
 
@@ -379,7 +379,7 @@ If `git status` shows no `.md` changes, the diff step is skipped — Stop hook f
 
 ### Citation convention
 
-The six writer-side skills (`crystallize`, `query`, `ingest`, `verify`, `graph`, `lint`) carry an identical footer instructing Claude to cite wiki pages inline as `[[page-slug]]`. The audit script counts these citations as a "wiki was actually consulted" signal in future iterations.
+The six writer-side skills (`crystallize`, `query`, `ingest`, `verify`, `graph`, `lint`) carry an identical footer instructing Claude to cite wiki pages inline as `[[page-slug]]`, which keeps them connected in the graph. The observability audit does not scan for these inline citations: it scores sessions on tool and command usage recorded by `hypo-session-record` (search / ingest / feedback counts). Counting citations as a signal is a possible future iteration, not current behavior.
 
 ---
 

package/docs/CONTRIBUTING.md

@@ -124,7 +124,8 @@ npm run lint       # scripts/lint.mjs — frontmatter + wikilink validation + W8
 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.
+                   # $HYPO_DIR or ~/hypomnema (source checkout only; not shipped in
+                   # the npm package). Does NOT grep ADR core decision lines.
 ```
 
 > **`fix:verify` needs an explicit `--spec`.** The default path
@@ -242,7 +243,7 @@ After both blocks, language-neutral:
 
 - **PR title**: Conventional Commits plus a scope, e.g. `feat(feedback): add failure_type enum`. The type drives the CHANGELOG section (see the classification table below).
 - **Merge commit**: the squash-merge subject carries the PR number (`#123`). That is where `#N` comes from, not the PR title. The two conventions stay separate.
-- Internal tracker ids (`FEAT-`, `IMPR-`, `ISSUE-`, `PRAC-`) may appear in your local notes and in source or workflow comments (an internal reference, like an ADR anchor), but never on the published changelog and release surface: not in the CHANGELOG body, not in the PR `## Changelog` block, not in a tag annotation, not in a GitHub Release. The only identifier that ships in those is the PR number `#N`. `check-tracker-ids --tag` gates the tag body; the migration keeps the CHANGELOG body clean.
+- Internal tracker ids (`FEAT-`, `IMPR-`, `ISSUE-`, `PRAC-`) may appear in your local notes and in `tests/` / `qa-runs/` (where they aid test-to-issue traceability and never reach an installed user), but not in shipped code or workflow comments, and never on the published changelog and release surface: not in the CHANGELOG body, not in the PR `## Changelog` block, not in a tag annotation, not in a GitHub Release. The only identifier that ships in those is the PR number `#N`. `check-tracker-ids` gates every surface (`--all`/`--staged` for files, `--commit-msg` for messages, `--tag` for the tag body); the migration keeps the CHANGELOG body clean.
 
 ### The `## Changelog` block
 
@@ -272,9 +273,9 @@ At and after the v1.2.0 cutoff, each non-empty gated section (`New Features`, `B
 ```
 ### New Features
 #### English
-- Feedback pages accept an optional `failure_type`. (#141)
+- Feedback pages accept an optional `failure_type`. ([#141](https://github.com/sk-lim19f/Hypomnema/pull/141))
 #### 한국어
-- 피드백 페이지가 선택적 `failure_type`를 받습니다. (#141)
+- 피드백 페이지가 선택적 `failure_type`를 받습니다. ([#141](https://github.com/sk-lim19f/Hypomnema/pull/141))
 ```
 
 Versions below the v1.2.0 cutoff (1.0.0, 1.0.1, 1.1.0) are English-only: the English body sits directly under the section header with no `####` sub-blocks. Korean is not back-filled for those releases.
@@ -283,12 +284,12 @@ The `### Changelog` index is language-neutral, one merged PR per line:
 
 ```
 ### Changelog
-- #141 feedback failure_type classification
-- #140 invalid-YAML lint guard
+- [#141](https://github.com/sk-lim19f/Hypomnema/pull/141) feedback failure_type classification
+- [#140](https://github.com/sk-lim19f/Hypomnema/pull/140) invalid-YAML lint guard
 Contributors: @handle
 ```
 
-Each line is `- #N <short title>`, no em dash. The `Contributors:` line lists that version's PR authors, de-duplicated; the release collector fills the handles from the GitHub API.
+Each line is `- [#N](<pr-url>) <short title>`, no em dash: the collector links each `#N` to its GitHub PR (a repo markdown file does not autolink a bare `#N`), deriving the URL from the `repository` field in `package.json`. The `Contributors:` line lists that version's PR authors, de-duplicated; the release collector fills the handles from the GitHub API.
 
 A `### Known Issues` or `### Notes` block, when a version has one, is a trailing note (a caveat, not a change). It is not one of the gated sections, so it carries no `####` sub-blocks even at or after the cutoff; bilingual text there is recommended, not enforced.
 

package/hooks/hypo-auto-commit.mjs

@@ -14,7 +14,7 @@ function hasRemote() {
 }
 
 // Stage + commit via the shared helper (same .hypoignore filter the apply path
-// uses — ADR 0056). A real commit failure short-circuits before sync, exactly as
+// uses). A real commit failure short-circuits before sync, exactly as
 // the inline logic did; "nothing to commit" is success and falls through to sync.
 const result = commitWikiChanges(HYPO_DIR);
 if (!result.committed) {
@@ -26,7 +26,7 @@ if (hasRemote()) {
   // pull/push failures must not stop the session, but they can no longer be
   // swallowed silently — syncRemote records each to .cache/sync-state.json and,
   // on a merge conflict, aborts the merge so the tree is never left half-merged
-  // (FEAT-17 hardening). session-start + doctor surface the result next session.
+  // (part of the v1.4 sync hardening). session-start + doctor surface the result next session.
   syncRemote(HYPO_DIR);
 }
 

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * hypo-auto-minimal-crystallize.mjs — Stop hook (ADR 0022 Layer 3)
+ * hypo-auto-minimal-crystallize.mjs — Stop hook (Layer 3)
  *
  * Last hook in the Stop chain: a final-line defense that blocks `Stop` when
  * the current session did substantial work (mutation, or a high-volume
@@ -8,7 +8,7 @@
  * session-close. Forces Claude to run minimal session-close before the
  * conversation context evaporates.
  *
- * Decision flow (see ADR 0022 amendment 2026-05-19 Q1+Q2 + 2nd amendment Q-close-gate):
+ * Decision flow (see amendment 2026-05-19 Q1+Q2 + 2nd amendment Q-close-gate):
  *
  *   1. stop_hook_active === true  → continue       (loop guard; PoC 2026-05-14)
  *   2. wiki absent                 → continue       (fail-open)
@@ -24,7 +24,7 @@
  * Close-intent gate (added after PR-C dogfooding revealed every-turn block —
  * codex 2-worker debate 2026-05-19, both REQUEST_CHANGES). Stop fires after
  * EVERY assistant turn, not at session end; blocking on "mutation + no marker"
- * alone nags the user on every turn of a long mutating session. ADR 0022's
+ * alone nags the user on every turn of a long mutating session. The hook's
  * real intent is "block when the session is ENDING and close is incomplete".
  * We approximate the end signal by reusing isClosePattern() over recent
  * user-message text (the same low-false-positive signal PreCompact uses):
@@ -82,11 +82,11 @@ function emitBlock(sessionId, transcriptPath, gate = null) {
   // The log-only escape hatch for a non-project (wiki/tooling-only)
   // session. Offered ONLY as an explicit alternative when a close blocker is
   // present — never as the default recovery, so a real project session is not
-  // taught to bypass the ADR 0043 close invariant (codex design Finding 3).
+  // taught to bypass the close invariant (codex design Finding 3).
   const logOnlyCmd = cliBase
     ? `${cliBase} --mark-session-closed --log-only --session-id=${sessionId}${transcriptHint}`
     : `/hypo:crystallize --log-only (session_id=${sessionId}${transcriptHint})`;
-  // ADR 0047: refine the message with the read-only /compact gate result.
+  // Refine the message with the read-only /compact gate result.
   // - gate green → the close is compact-ready and ONLY the marker is missing
   //   (the hand-edit close case: files Written + committed directly, bypassing
   //   the marker writer). Say so precisely + give the one command, instead of
@@ -112,7 +112,7 @@ function emitBlock(sessionId, transcriptPath, gate = null) {
     JSON.stringify({
       decision: 'block',
       reason,
-      stopReason: 'session-close incomplete (ADR 0022 Layer 3)',
+      stopReason: 'session-close incomplete (Layer 3)',
     }),
   );
 }
@@ -186,7 +186,7 @@ process.stdin.on('end', () => {
       return;
     }
 
-    // ADR 0047: read-only /compact gate (same precompactGateStatus the real
+    // Read-only /compact gate (same precompactGateStatus the real
     // PreCompact hook uses) sharpens the block message — distinguishes "close
     // is compact-ready, only the marker is missing" from "there are real
     // blockers". The hook NEVER writes the marker here (file-header invariant);

package/hooks/hypo-compact-guard.mjs

@@ -2,7 +2,7 @@
 /**
  * hypo-compact-guard.mjs — UserPromptSubmit hook
  *
- * Scope: detects "/compact" or "/clear" typed in chat only (ADR 0022 Layer 2).
+ * Scope: detects "/compact" or "/clear" typed in chat only (Layer 2).
  * The CLI built-in /compact does NOT fire UserPromptSubmit — use personal-wiki-check.mjs
  * (PreCompact hook) as the hard gate for that path. /clear has no PreCompact event, so
  * this hook is the only chat-side gate that can prompt session-close before context wipe.
@@ -42,7 +42,7 @@ process.stdin.on('end', () => {
     const gitStatus = hypoIsClean();
     const hotStatus = hotMdIsClean();
 
-    // ADR 0056: block on uncommitted (real unsaved work); unpushed commits (ahead)
+    // 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) {

package/hooks/hypo-cwd-change.mjs

@@ -6,8 +6,7 @@
  * project hot.md. Skips if still within the same project subtree.
  */
 
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
-import { homedir } from 'os';
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
 import { join } from 'path';
 import {
   HYPO_DIR,
@@ -19,6 +18,9 @@ import {
   buildProjectSuggestionLine,
   recordSuggestionCooldown,
   sanitizeProjForPrompt,
+  pickProjectByCwd,
+  collectProjectWorkingDirs,
+  buildVaultOrientation,
 } from './hypo-shared.mjs';
 
 const PROJECTS_DIR = join(HYPO_DIR, 'projects');
@@ -33,42 +35,26 @@ function readIfNotIgnored(path, patterns) {
   return readFileSync(path, 'utf-8').slice(0, MAX_CHARS);
 }
 
-function parseFrontmatterField(content, key) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return null;
-  const line = match[1].split('\n').find((l) => l.startsWith(`${key}:`));
-  if (!line) return null;
-  return line
-    .slice(key.length + 1)
-    .trim()
-    .replace(/^['"]|['"]$/g, '');
-}
-
 function findProjectHot(cwd) {
   if (!existsSync(PROJECTS_DIR)) return null;
-  for (const proj of readdirSync(PROJECTS_DIR)) {
-    const projDir = join(PROJECTS_DIR, proj);
-    if (!statSync(projDir).isDirectory()) continue;
-    const indexPath = join(projDir, 'index.md');
-    if (!existsSync(indexPath)) continue;
-    const content = readFileSync(indexPath, 'utf-8');
-    const workingDir = parseFrontmatterField(content, 'working_dir');
-    if (!workingDir) continue;
-    const resolved = workingDir.startsWith('~/')
-      ? join(homedir(), workingDir.slice(2))
-      : workingDir;
-    if (cwd === resolved || cwd.startsWith(resolved + '/')) {
-      const hotPath = join(projDir, 'hot.md');
-      const statePath = join(projDir, 'session-state.md');
-      return {
-        proj,
-        hotPath: existsSync(hotPath) ? hotPath : null,
-        statePath: existsSync(statePath) ? statePath : null,
-        resolved,
-      };
-    }
+  let realpathCwd = null;
+  try {
+    realpathCwd = realpathSync(cwd);
+  } catch {
+    realpathCwd = null;
   }
-  return null;
+  // Two-tier match (absolute prefix, then cross-machine unique basename) so a
+  // vault synced from another machine still resolves the cwd to its project.
+  const proj = pickProjectByCwd(collectProjectWorkingDirs(HYPO_DIR), cwd, { realpathCwd });
+  if (!proj) return null;
+  const projDir = join(PROJECTS_DIR, proj);
+  const hotPath = join(projDir, 'hot.md');
+  const statePath = join(projDir, 'session-state.md');
+  return {
+    proj,
+    hotPath: existsSync(hotPath) ? hotPath : null,
+    statePath: existsSync(statePath) ? statePath : null,
+  };
 }
 
 let raw = '';
@@ -123,10 +109,14 @@ process.stdin.on('end', () => {
           );
         }
       }
+      // Same vault orientation as session-start: when the new cwd is a project
+      // working_dir distinct from the vault, surface where wiki files live.
+      const vaultOrientation = buildVaultOrientation(newCwd);
+      const orientPrefix = vaultOrientation ? `${vaultOrientation}\n\n` : '';
       console.log(
         JSON.stringify(
           buildOutput(
-            `[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
+            `${orientPrefix}[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
             {
               continue: true,
               suppressOutput: true,
@@ -137,7 +127,7 @@ process.stdin.on('end', () => {
       return;
     }
 
-    // MISS: cwd matches no project. ADR 0023 — offer to create one
+    // MISS: cwd matches no project. Offer to create one
     // when the trigger conditions hold. Same nudge-only model as session-start.
     let suggestPrefix = '';
     if (shouldSuggestProjectCreation(newCwd, HYPO_DIR)) {

package/hooks/hypo-lookup.mjs

@@ -11,7 +11,15 @@
 
 import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, basename } from 'path';
-import { HYPO_DIR, buildOutput, loadHypoIgnore, isIgnored } from './hypo-shared.mjs';
+import {
+  HYPO_DIR,
+  buildOutput,
+  loadHypoIgnore,
+  isIgnored,
+  staleMarkerFor,
+  pageUsageLoggingAllowed,
+  recordLookupUsage,
+} from './hypo-shared.mjs';
 
 const INDEX_PATH = join(HYPO_DIR, 'index.md');
 const MAX_HITS = 3;
@@ -178,6 +186,8 @@ process.stdin.on('end', () => {
   try {
     const data = JSON.parse(input);
     const prompt = (data.prompt || '').trim();
+    // Runtime sends a session UUID; older payloads may omit it (parse defensively).
+    const sessionId = data.session_id || null;
 
     if (!prompt || !existsSync(INDEX_PATH)) {
       console.log(JSON.stringify({ continue: true, suppressOutput: true }));
@@ -235,14 +245,32 @@ process.stdin.on('end', () => {
       ),
     };
 
+    // UTC to match doctor.mjs' overdue set (D1/D2). STALE is advisory, so a
+    // one-day UTC/local skew never misleads.
+    const TODAY = new Date().toISOString().slice(0, 10);
+
     const injected = [];
+    const injectedSlugs = [];
     for (const { slug } of matched.slice(0, MAX_HITS)) {
       const path =
         pageMap[slug] ??
         pageMap[slug.replace(/^(pages|projects)\//, '')] ??
         pageMap[basename(slug)];
       if (path && existsSync(path)) {
-        injected.push(`=== [[${slug}]] ===\n${readFileSync(path, 'utf-8').slice(0, MAX_CHARS)}`);
+        const raw = readFileSync(path, 'utf-8');
+        // Compute the marker on raw (pre-slice) so a long body can't truncate
+        // frontmatter out of reach. fail-open: a marker failure drops the marker,
+        // never the page.
+        let marker = '';
+        try {
+          marker = staleMarkerFor(raw, TODAY);
+        } catch {
+          marker = '';
+        }
+        injected.push(
+          `=== [[${slug}]] ===\n${marker ? marker + '\n' : ''}${raw.slice(0, MAX_CHARS)}`,
+        );
+        injectedSlugs.push(slug);
       }
     }
 
@@ -262,6 +290,13 @@ process.stdin.on('end', () => {
       return;
     }
 
+    // Page-usage logging (B): observability only, gated fail-closed on commit
+    // coverage, and fail-open so it never disturbs the injection above. Only the
+    // real HIT branch reaches here (miss / index-hit-but-missing returned early).
+    if (pageUsageLoggingAllowed(HYPO_DIR, sessionId)) {
+      recordLookupUsage(HYPO_DIR, { sessionId, slugs: injectedSlugs });
+    }
+
     const overflow =
       matched.length > MAX_HITS
         ? `\n(+${matched.length - MAX_HITS} more matches — search wiki index for more)`

package/hooks/hypo-personal-check.mjs

@@ -9,13 +9,13 @@
  *   - hot.md has forbidden structure
  *   - lint blockers exist
  *
- * Bypass options (checked in order, per ADR 0022 / spec §7.5):
+ * Bypass options (checked in order, per spec §7.5):
  *   1. HYPO_SKIP_GATE=1 env var
  *   2. HYPO_SKIP_GATE=1 in a recent *user-role* transcript message
  *      (assistant/tool output is excluded to prevent self-triggering from block reason text)
  *
  * NOTE: capacity bypass (wiki-context-critical.json ≥90%) was REMOVED
- * (ADR 0022 amendment 2026-05-13). Spec §7.5: even at full context, minimal
+ * (amendment 2026-05-13). Spec §7.5: even at full context, minimal
  * session-close is mandatory — auto-bypass on capacity caused silent state loss.
  */
 
@@ -31,6 +31,7 @@ import {
   isGateSkipped,
   isClosePattern,
   extractUserMessages,
+  isUnderProjectDirs,
 } from './hypo-shared.mjs';
 
 const WARNING_FILE = join(homedir(), '.claude', 'state', 'wiki-context-warning.json');
@@ -52,7 +53,7 @@ process.stdin.on('end', () => {
     /* fail-open */
   }
 
-  // ── Capacity bypass (≥90%) REMOVED — ADR 0022 amendment 2026-05-13.
+  // ── Capacity bypass (≥90%) REMOVED: amendment 2026-05-13.
   //    Even at full context, minimal session-close is mandatory (spec §7.5).
   //    Bypass paths are now only: HYPO_SKIP_GATE env / HYPO_SKIP_GATE in transcript.
 
@@ -93,12 +94,12 @@ process.stdin.on('end', () => {
   // ── Heavy checks ──
   const today = new Date().toISOString().slice(0, 10);
 
-  // The full PreCompact gate decision, single-sourced (ADR 0046). The SAME
+  // The full PreCompact gate decision, single-sourced. The SAME
   // function backs `crystallize --check-session-close`, so a green self-check
   // there means this hook will not block. precompactGateStatus runs git-clean +
-  // hot.md structure + session-close files (ADR 0043 global invariant) + scoped
+  // hot.md structure + session-close files (global invariant) + scoped
   // lint + W8 design-history + feedback projection. The transcript widens the
-  // lint scope to this session's edited files (ADR 0041); without one the scope
+  // lint scope to this session's edited files; without one the scope
   // is the mandatory close files. Read-only: pure feedback drift comes back as
   // gate.driftTargets, a self-heal effect requirement we run as --write below.
   let gate;
@@ -116,7 +117,7 @@ process.stdin.on('end', () => {
     return;
   }
 
-  // Self-heal pure feedback projection drift (ADR 0045): the one mutation the
+  // Self-heal pure feedback projection drift: the one mutation the
   // read-only gate leaves to the caller. Fails CLOSED — if the --write errors we
   // turn the (otherwise non-blocking) drift into a blocker, since real drift is
   // confirmed and silently passing it would defeat the gate. --write only applies
@@ -152,20 +153,34 @@ process.stdin.on('end', () => {
   }
 
   // Non-blocking heads-up about pre-existing lint / out-of-scope design-history
-  // debt in untouched files (other projects / shared pages). Surfaced so it is
-  // visible but never blocks compact. (Mirrors the pre-ADR-0046 inline behavior,
-  // which lumped out-of-scope W8 into the same lint-notice list.)
+  // debt in untouched files. Surfaced so it is visible but never blocks compact.
+  // Scoped to the close-target (today-active) projects: debt under one of their
+  // dirs stays listed by filename; debt elsewhere (other projects, shared pages,
+  // root files) folds into a count so the same untouched-file debt does not
+  // re-list its filenames on every compact. Non-file diagnostics (a fail-open
+  // "lint skipped" notice carries no path) are preserved verbatim, never folded.
   const debtNotices = gate.notices.filter((n) => n.type === 'lint' || n.type === 'design-history');
-  let noticeText =
-    debtNotices.length > 0
-      ? `[WIKI CHECK] ${debtNotices.length} pre-existing lint issue(s) in files this session did not touch (not blocking): ${[
-          ...new Set(debtNotices.map((n) => n.reason.replace(/ \([^)]*\)$/, ''))),
-        ]
-          .slice(0, 5)
-          .join(', ')}${debtNotices.length > 5 ? ', …' : ''} — clean up when convenient.`
-      : '';
+  const activeSlugs = (gate.close?.projects || []).map((p) => p.project).filter(Boolean);
+  const nonFileNotices = debtNotices.filter((n) => !n.file);
+  const fileNotices = debtNotices.filter((n) => n.file);
+  const inScopeNotices = fileNotices.filter((n) => isUnderProjectDirs(n.file, activeSlugs));
+  const otherDebtCount = fileNotices.length - inScopeNotices.length;
+  const listed = [
+    ...nonFileNotices.map((n) => n.reason),
+    ...new Set(inScopeNotices.map((n) => n.reason.replace(/ \([^)]*\)$/, ''))),
+  ];
+  let noticeText = '';
+  if (listed.length > 0) {
+    noticeText = `[WIKI CHECK] ${listed.length} pre-existing lint issue(s) in files this session did not touch (not blocking): ${listed
+      .slice(0, 5)
+      .join(', ')}${listed.length > 5 ? ', …' : ''} — clean up when convenient.`;
+  }
+  if (otherDebtCount > 0) {
+    const fold = `+${otherDebtCount} pre-existing lint issue(s) elsewhere in the vault (other projects / shared pages, not blocking) — run \`/hypo:lint\` for the full list.`;
+    noticeText = noticeText ? `${noticeText}\n${fold}` : `[WIKI CHECK] ${fold}`;
+  }
   // Surface the self-heal so a re-synced projection is not a silent mutation of
-  // the user's MEMORY.md / CLAUDE.md (ADR 0045 transparency).
+  // the user's MEMORY.md / CLAUDE.md (transparency).
   if (feedbackHealed) noticeText = noticeText ? `${noticeText}\n${feedbackHealed}` : feedbackHealed;
 
   if (gate.ok) {
@@ -200,7 +215,7 @@ process.stdin.on('end', () => {
   // ── Block ──
   // gate.blockers already carry per-type reasons in the canonical order
   // (git, hot, close, lint, design-history, feedback) — same strings as before
-  // ADR 0046, now sourced from the shared gate instead of inline checks.
+  // Now sourced from the shared gate instead of inline checks.
   const reasons = [
     ...gate.blockers.map((b) => b.reason),
     gate.skipped.lint ? 'lint skipped (run `hypomnema init` to enable lint gate)' : '',
@@ -224,10 +239,10 @@ 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. lint — run scripts/lint.mjs; fix errors in files YOU touched`,
+      `  [ ] 12. lint — run /hypo:lint; fix errors in files YOU touched`,
       `           (other projects' / shared-page debt is reported as non-blocking notice)`,
       `  [ ] 13. git commit & push`,
-      `  [ ] 14. verify — run \`crystallize.mjs --check-session-close\`; only declare`,
+      `  [ ] 14. verify — run /hypo:crystallize (--check-session-close mode); only declare`,
       `           the session closed once it prints "Compact-ready" (= this gate passes).`,
     ].join('\n');
 

package/hooks/hypo-session-end.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * hypo-session-end.mjs — SessionEnd hook (ADR 0022 Layer 2)
+ * hypo-session-end.mjs — SessionEnd hook (Layer 2)
  *
  * `/clear` cannot be blocked: it never fires UserPromptSubmit (Stage 0 PoC,
  * 2026-05-14). The only intervention point is the SessionEnd(reason='clear')

package/hooks/hypo-session-record.mjs

@@ -5,7 +5,7 @@
  * Appends an entry to ~/hypomnema/.cache/sessions/index.jsonl for each
  * completed session. The index.jsonl is the **primary** source for
  * scripts/session-audit.mjs (which falls back to ~/.claude/projects/<encoded>/
- * if the index is empty or missing — see ADR 0019).
+ * if the index is empty or missing).
  *
  * Silent: never blocks, never emits user-visible output.
  */
@@ -51,7 +51,7 @@ process.stdin.on('end', () => {
       transcript_path: transcriptPath,
       recorded_at: new Date().toISOString(),
       cwd: payload.cwd || process.cwd(),
-      // PRAC-17: machine identity for multi-machine audit. index.jsonl lives
+      // machine identity for multi-machine audit. index.jsonl lives
       // under .cache/ (gitignored in a normal vault), so this is a LOCAL-only
       // per-session record — accurate for every session, no sync/privacy cost.
       device: hostname() || 'unknown',