hypomnema 1.4.1 → 1.5.0

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

package/hooks/hypo-session-start.mjs

@@ -7,7 +7,7 @@
  *   MISS → inject global hot.md pointer only (no fan-out to all projects)
  */
 
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -28,6 +28,9 @@ import {
   buildProjectSuggestionLine,
   recordSuggestionCooldown,
   sanitizeProjForPrompt,
+  pickProjectByCwd,
+  collectProjectWorkingDirs,
+  buildVaultOrientation,
 } from './hypo-shared.mjs';
 import {
   defaultCachePath,
@@ -124,7 +127,7 @@ function buildUpdateNotice() {
 }
 
 /**
- * Stale-sibling notice (ADR 0038, D3). The update-notifier above only knows
+ * Stale-sibling notice (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.
@@ -176,7 +179,7 @@ function readLastGrowthLine() {
 }
 
 /**
- * ADR 0022 amendment 2026-05-14: if the prior session ended
+ * Amendment 2026-05-14: if the prior session ended
  * via `/clear`, hypo-session-end stashed its identity in `.cache/clear-marker.json`.
  * Read it (with 7-day stale guard), unlink it (one-shot), and return a
  * `[WIKI_AUTOCLOSE]` recovery line for additionalContext + stderr.
@@ -256,41 +259,26 @@ const GLOBAL_HOT = join(HYPO_DIR, 'hot.md');
 const HOT_CHARS = 2000;
 const STATE_CHARS = 2000;
 
-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 findProjectFiles(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,
-      };
-    }
+  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,
+  };
 }
 
 function extractSection(content, heading) {
@@ -343,7 +331,7 @@ process.stdin.on('end', () => {
     const pullOk = gitPull(HYPO_DIR);
     const syncLine = syncStateNotice(pullOk);
     const growthLine = readLastGrowthLine();
-    // ADR 0022 amendment: on source='clear', surface the dying
+    // 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.
@@ -377,6 +365,12 @@ process.stdin.on('end', () => {
 
     const ignorePatterns = loadHypoIgnore(HYPO_DIR);
 
+    // When cwd is a project working_dir that is NOT the vault itself, tell the
+    // AI where the vault lives so it does not re-discover the path or look for
+    // wiki files in the code repo. '' when cwd === vault root.
+    const vaultOrientation = hit ? buildVaultOrientation(cwd) : '';
+    const hitPrefix = vaultOrientation ? `${vaultOrientation}\n\n` : '';
+
     if (hit) {
       const hotContent = readIfNotIgnored(hit.hotPath, HOT_CHARS, ignorePatterns);
       const stateContent = readIfNotIgnored(hit.statePath, STATE_CHARS, ignorePatterns);
@@ -399,7 +393,7 @@ process.stdin.on('end', () => {
         console.log(
           JSON.stringify(
             buildOutput(
-              `${noticePrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}]\n\n${parts.join('\n\n')}`,
+              `${noticePrefix}${hitPrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}]\n\n${parts.join('\n\n')}`,
               outExtra,
             ),
           ),
@@ -415,7 +409,7 @@ process.stdin.on('end', () => {
         console.log(
           JSON.stringify(
             buildOutput(
-              `${noticePrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}, no snapshot yet]`,
+              `${noticePrefix}${hitPrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}, no snapshot yet]`,
               outExtra,
             ),
           ),
@@ -424,8 +418,8 @@ process.stdin.on('end', () => {
       return;
     }
 
-    // MISS: cwd matches no project. ADR 0023 — offer to create one
-    // when the ADR trigger conditions hold (git repo + project marker + no
+    // MISS: cwd matches no project. Offer to create one
+    // when the trigger conditions hold (git repo + project marker + no
     // cooldown + not previously declined). The actual scaffold is the LLM's
     // job on a "Y" reply (scripts/lib/project-create.mjs); the hook only nudges.
     if (shouldSuggestProjectCreation(cwd, HYPO_DIR)) {