hypomnema 1.4.2 → 1.5.1

package/scripts/lib/wd-match.mjs

@@ -0,0 +1,181 @@
+/**
+ * scripts/lib/wd-match.mjs — shared cwd ↔ working_dir project matcher.
+ *
+ * The four readers (resume.mjs, hooks/hypo-shared.mjs, hooks/hypo-session-start.mjs,
+ * hooks/hypo-cwd-change.mjs) each used to inline the same prefix-match. This
+ * module is the single source of truth they delegate the path logic to, so the
+ * cross-machine basename fallback below is implemented (and tested) once.
+ *
+ * The cross-machine problem: a git-synced vault carries one machine's absolute
+ * working_dir to every machine, so on a second machine cwd never prefix-matches
+ * and cwd-first resume silently degrades to recency. The basename tier recovers
+ * the match WITHOUT a synced map or a writer: when the absolute prefix fails, a
+ * cwd ancestor whose directory name is a GLOBALLY unique project working_dir
+ * basename identifies the project. Unique-only, so a shared repo dirname fails
+ * closed back to recency (the original prefix-only behavior).
+ *
+ * The matcher (pickProjectByCwd) is PURE — no fs. collectProjectWorkingDirs is
+ * the disk companion that builds the project universe the matcher reasons over.
+ */
+
+import { homedir } from 'os';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// Expand a leading `~`/`~/`, strip trailing slashes. Mirrors the inline
+// expansion the readers did, kept here so every caller normalizes identically.
+// Returns null for empty/falsy input.
+export function normalizeWorkingDir(p) {
+  if (!p) return null;
+  let s = String(p).trim();
+  if (s === '~') s = homedir();
+  else if (s.startsWith('~/')) s = `${homedir()}/${s.slice(2)}`;
+  s = s.replace(/\/+$/, '');
+  return s || null;
+}
+
+// macOS (APFS/HFS+ default) and Windows match paths case-insensitively, so a
+// case-only difference between cwd and a recorded working_dir is the SAME dir
+// there and a genuinely different dir on Linux. Fold only on those platforms:
+// on Linux folding stays off, preserving the exact original comparison.
+export function isCaseInsensitiveFs(platform = process.platform) {
+  return platform === 'darwin' || platform === 'win32';
+}
+
+function casefold(s, ci) {
+  return ci ? s.toLowerCase() : s;
+}
+
+// Trailing path segment (basename) without importing path — paths here are
+// already normalized (no trailing slash). Returns '' for a bare root.
+function lastSegment(p) {
+  const i = p.lastIndexOf('/');
+  return i < 0 ? p : p.slice(i + 1);
+}
+
+/**
+ * Resolve which project a cwd belongs to.
+ *
+ * @param {{slug:string, workingDir:string|null|undefined}[]} projects
+ *   EVERY project with an index.md (the universe). The basename-uniqueness gate
+ *   is computed over all of them, so an unrelated project sharing a dirname
+ *   correctly disqualifies the basename tier (fail closed).
+ * @param {string} cwd  process.cwd()
+ * @param {object} [opts]
+ * @param {string[]|null} [opts.eligible]  restrict the ANSWER to these slugs
+ *   (e.g. resume's hot.md rows); uniqueness is still judged over all `projects`.
+ *   null = any project is an acceptable answer.
+ * @param {string|null} [opts.realpathCwd]  realpathSync(cwd), if the caller
+ *   resolved symlinks. Tried in addition to the raw cwd.
+ * @param {boolean} [opts.caseInsensitive]  override FS case sensitivity (tests).
+ * @returns {string|null} matched slug, or null when nothing matches.
+ */
+export function pickProjectByCwd(projects, cwd, opts = {}) {
+  const { eligible = null, realpathCwd = null, caseInsensitive = isCaseInsensitiveFs() } = opts;
+  if (!cwd && !realpathCwd) return null;
+
+  const eligibleSet = eligible ? new Set(eligible) : null;
+  const isEligible = (slug) => !eligibleSet || eligibleSet.has(slug);
+
+  // Universe of normalized (slug, path) entries with a real working_dir.
+  const entries = [];
+  for (const p of projects) {
+    const path = normalizeWorkingDir(p.workingDir);
+    if (path) entries.push({ slug: p.slug, path });
+  }
+  if (entries.length === 0) return null;
+
+  // cwd variants in PRIORITY order: raw first, realpath (symlink-resolved) only
+  // as a fallback. A raw-cwd match must not be overridden by a realpath match
+  // (preserves the original single-cwd behavior; realpath only rescues misses).
+  const cwds = [];
+  for (const c of [cwd, realpathCwd]) {
+    const n = normalizeWorkingDir(c);
+    if (n && !cwds.includes(n)) cwds.push(n);
+  }
+
+  // ── Tier 1: longest absolute prefix (the original behavior) ────────────────
+  // cwd === path or cwd under path/. Longest path wins so /repo/sub beats /repo.
+  // The FIRST cwd variant that yields any prefix match wins (raw before realpath).
+  for (const c of cwds) {
+    const cf = casefold(c, caseInsensitive);
+    let bestSlug = null;
+    let bestLen = -1;
+    for (const e of entries) {
+      if (!isEligible(e.slug)) continue;
+      const pf = casefold(e.path, caseInsensitive);
+      if ((cf === pf || cf.startsWith(`${pf}/`)) && e.path.length > bestLen) {
+        bestLen = e.path.length;
+        bestSlug = e.slug;
+      }
+    }
+    if (bestSlug) return bestSlug;
+  }
+
+  // ── Tier 2: globally-unique basename of a cwd ancestor (cross-machine) ─────
+  // Count basenames across the WHOLE universe. A basename is usable only when
+  // exactly one project carries it, so a shared dirname falls through to null.
+  const byBasename = new Map(); // folded basename -> { slug, count }
+  for (const e of entries) {
+    const b = casefold(lastSegment(e.path), caseInsensitive);
+    if (!b) continue;
+    const hit = byBasename.get(b);
+    if (hit) hit.count += 1;
+    else byBasename.set(b, { slug: e.slug, count: 1 });
+  }
+
+  // For each cwd variant (raw first), collect every ancestor whose basename is a
+  // globally-unique, eligible project basename. Use it ONLY when the whole chain
+  // points at exactly ONE project: if two different projects match along the
+  // path (e.g. cwd /x/monorepo/api with both `monorepo` and `api` registered),
+  // cwd alone can't disambiguate, so decline and let the caller fall back to
+  // recency (fail closed, no wrong-project guess).
+  for (const c of cwds) {
+    const matched = new Set();
+    let cur = c;
+    while (cur && cur.includes('/')) {
+      const b = casefold(lastSegment(cur), caseInsensitive);
+      const hit = b && byBasename.get(b);
+      if (hit && hit.count === 1 && isEligible(hit.slug)) matched.add(hit.slug);
+      cur = cur.slice(0, cur.lastIndexOf('/'));
+    }
+    if (matched.size === 1) return [...matched][0];
+  }
+  return null;
+}
+
+/**
+ * Scan projects/<slug>/index.md and return [{slug, workingDir}] for every real
+ * project. Skips `_template` and dirs without an index.md. The full set is the
+ * uniqueness universe for tier 2, so callers should pass ALL projects here even
+ * when they later restrict the answer via `opts.eligible`.
+ *
+ * @param {string} hypoDir
+ * @returns {{slug:string, workingDir:string|null}[]}
+ */
+export function collectProjectWorkingDirs(hypoDir) {
+  const projectsDir = join(hypoDir, 'projects');
+  if (!existsSync(projectsDir)) return [];
+  const out = [];
+  for (const slug of readdirSync(projectsDir)) {
+    if (slug === '_template') continue;
+    const dir = join(projectsDir, slug);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const indexPath = join(dir, 'index.md');
+    if (!existsSync(indexPath)) continue;
+    let workingDir = null;
+    try {
+      const fm = parseFrontmatter(readFileSync(indexPath, 'utf-8'));
+      workingDir = fm?.working_dir ?? null;
+    } catch {
+      workingDir = null;
+    }
+    out.push({ slug, workingDir });
+  }
+  return out;
+}

package/scripts/lib/wikilink.mjs

@@ -7,7 +7,7 @@
 //   - scripts/graph.mjs       (slug index, page collection, link extraction)
 //   - scripts/crystallize.mjs (page collection, link extraction)
 //
-// IMPR-13 consolidation. Before this lib, each script carried its own copy of
+// Shared-resolver consolidation. Before this lib, each script carried its own copy of
 // collectPages + a slug-form deriver, drifting in subtle ways. The four
 // collectPages variants are NOT interchangeable — they differ deliberately in
 // traversal/security/output-shape policy (codex design review, CONCERN):

package/scripts/lint.mjs

@@ -115,7 +115,7 @@ const TYPE_CONDITIONAL_FIELDS = {
   'tool-eval': ['status'],
   postmortem: ['outcome'],
   learning: ['source'],
-  // feedback: ADR 0031 — projection SoT requires full classification
+  // feedback: projection SoT requires full classification
   feedback: [
     'status',
     'scope',
@@ -136,13 +136,13 @@ const TYPE_ENUM_FIELDS = {
   prd: { status: ['draft', 'active', 'completed', 'cancelled', 'archived'] },
   adr: { status: ['proposed', 'accepted', 'deprecated', 'superseded'] },
   'tool-eval': { status: ['adopted', 'evaluating', 'rejected'] },
-  // feedback: ADR 0031 — sensitivity:private is forbidden (wiki is a
+  // feedback: sensitivity:private is forbidden (wiki is a
   // git-pushed public surface)
   feedback: {
     status: ['active', 'superseded', 'archived'],
     tier: ['L1', 'L2'],
     sensitivity: ['public', 'sanitized'],
-    // FEAT-1: optional failure taxonomy. The enum loop guards on `if (fm[field])`,
+    // optional failure taxonomy. The enum loop guards on `if (fm[field])`,
     // so an omitted failure_type is never validated (optional, migration-safe).
     failure_type: FAILURE_TYPE_ENUM,
   },
@@ -283,7 +283,7 @@ const issues = [];
 //                             double-gate).
 // NOTE: no gate currently passes --strict (npm run lint / CI / release.yml /
 // crystallize / the close-gate all run plain lint), so promotion is
-// forward-looking — these surface as warnings today. IMPR-3's deliverable is
+// forward-looking: these surface as warnings today. The deliverable is
 // "stop silently green-passing invalid YAML"; the W9 warning satisfies that.
 const STRICT_PROMOTE_IDS = new Set(['W1', 'W2', 'W4', 'W9']);
 
@@ -392,7 +392,7 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs, validTypes) {
     }
   }
 
-  // feedback: scope vocabulary + conditional claude-learned fields (ADR 0031)
+  // feedback: scope vocabulary + conditional claude-learned fields
   if (fm.type === 'feedback') {
     const scope = fm.scope || '';
     if (scope && !FEEDBACK_SCOPE_RE.test(scope)) {

package/scripts/rename.mjs

@@ -234,7 +234,7 @@ function fail(args, msg) {
 //  • A directory move does NOT change basenames, only the path prefix. So bare
 //    `[[0052]]` links keep resolving to the relocated page automatically and need
 //    NO rewrite — only the FULL-slug and 1-seg DIR-RELATIVE forms encode the moved
-//    prefix and break. (Forms that drop ≥2 segments, e.g. `[[decisions/0052]]`, do
+//    prefix and break. (Forms that drop ≥2 segments, e.g. `[[decisions/NNNN]]`, do
 //    not encode the renamed prefix either: lint cannot resolve them today and they
 //    survive a move unchanged — out of scope, matching lint's buildSlugMap.)
 //  • Every moved page is BOTH a target (it relocates) and a source (its links to

package/scripts/resume.mjs

@@ -26,10 +26,10 @@
  *   --json                Output as JSON
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { pickProjectByCwd, collectProjectWorkingDirs } from './lib/wd-match.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -60,27 +60,25 @@ function parseFrontmatterField(content, key) {
     .replace(/^['"]|['"]$/g, '');
 }
 
-// Among `slugs`, return the one whose projects/<slug>/index.md `working_dir`
-// is the LONGEST prefix of cwd (so /repo/sub wins over /repo). Returns null
-// when cwd is falsy or matches none. resume gives this authority OVER recency
-// (ADR 0044): a cwd↔working_dir match wins regardless of which row is newest.
+// Return the project (among `slugs`) that owns cwd: a longest-prefix
+// working_dir match, or — when no absolute path matches because the vault was
+// synced from another machine — a cwd ancestor whose directory name is a
+// globally-unique project basename. Uniqueness is judged over EVERY project on
+// disk (not just `slugs`), so a shared dirname declines and falls back to
+// recency. resume gives this authority over recency: a cwd↔project match wins
+// regardless of which hot.md row is newest.
 function pickByCwd(hypoDir, slugs, cwd) {
   if (!cwd) return null;
-  let best = null;
-  let bestLen = -1;
-  for (const slug of slugs) {
-    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
-    if (!existsSync(indexPath)) continue;
-    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
-    if (!wd) continue;
-    let resolved = wd.startsWith('~/') ? join(homedir(), wd.slice(2)) : wd;
-    resolved = resolved.replace(/\/+$/, ''); // trailing-slash normalize
-    if ((cwd === resolved || cwd.startsWith(resolved + '/')) && resolved.length > bestLen) {
-      bestLen = resolved.length;
-      best = slug;
-    }
+  let realpathCwd = null;
+  try {
+    realpathCwd = realpathSync(cwd);
+  } catch {
+    realpathCwd = null;
   }
-  return best;
+  return pickProjectByCwd(collectProjectWorkingDirs(hypoDir), cwd, {
+    eligible: slugs,
+    realpathCwd,
+  });
 }
 
 // When cwd is set but no project's working_dir matches it, resume falls back to
@@ -125,11 +123,11 @@ function resolveActiveProject(hypoDir, cwd = null) {
     ),
   ].map((m) => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
   if (wikiRows.length > 0) {
-    // cwd-first (ADR 0044): a cwd↔working_dir match wins over recency, across
+    // cwd-first: a cwd↔working_dir match wins over recency, across
     // ALL rows (not just a same-date tie). The user is physically in that
     // project, so cwd is a stronger intent signal than "some other project was
     // touched more recently". This reverses the earlier tie-breaker-only
-    // semantics now that resume=cwd-positive (ADR 0043). Tradeoff: a stale cwd
+    // semantics now that resume=cwd-positive. Tradeoff: a stale cwd
     // match can mask a genuinely newer project; `--project` overrides. close
     // callers pass null → recency path below (resume=cwd-positive / close=no-pick).
     if (cwd) {

package/scripts/session-audit.mjs

@@ -6,7 +6,7 @@
  * (search count, ingest count, URLs mentioned, feedback count) so the
  * weekly observability report (Lane E) can compute autonomy scores.
  *
- * Transcript dual-source (ADR 0019):
+ * Transcript dual-source:
  *   1) Primary: <hypo-dir>/.cache/sessions/index.jsonl
  *      Written by hooks/hypo-session-record.mjs (Stop hook).
  *   2) Fallback: ~/.claude/projects/<encoded>/*.jsonl

package/scripts/stats.mjs

@@ -48,8 +48,8 @@ function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
 // Local top-level-only extractor, behavior-aligned with lib/frontmatter.mjs:
 // skip indented / list lines, first-wins, strip a trailing `# comment`. Without
 // the comment strip a `failure_type: overreach # note` would aggregate under the
-// literal "overreach # note" key (FEAT-1). Kept local (not the shared import) to
-// hold stats' dependency surface flat per the FEAT-1 scope split.
+// literal "overreach # note" key. Kept local (not the shared import) to
+// hold stats' dependency surface flat per the scope split.
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
@@ -101,7 +101,7 @@ const sources = existsSync(join(args.hypoDir, 'sources'))
   : [];
 
 const typeCounts = {};
-const failureTypeCounts = {}; // FEAT-1: feedback pages carrying a failure_type
+const failureTypeCounts = {}; // feedback pages carrying a failure_type
 let missingFrontmatter = 0;
 
 for (const f of pageFiles) {

package/scripts/uninstall.mjs

@@ -15,7 +15,7 @@
  *   --force-extensions   Remove user-modified extension files (hypo-ext-*) instead of preserving them
  *   --hooks-dir=<path>   Override Claude hooks directory (default: ~/.claude/hooks)
  *
- * Extensions (ADR 0024): hypo-ext-* hard-copies under
+ * Extensions: hypo-ext-* hard-copies under
  * ~/.claude/{hooks,commands,skills,agents}/ and ~/.codex/{hooks,commands}/ (with
  * --codex) are removed when their on-disk SHA matches the recorded one in
  * ~/.claude/hypo-pkg.json#extensions.<target>. User-modified copies are preserved
@@ -94,7 +94,7 @@ function removeCommands(apply, force) {
   return { removed, skippedUserModified, skippedNonRegular };
 }
 
-// ── extensions removal (ADR 0024) ───────────────────────────────────
+// ── extensions removal ───────────────────────────────────
 
 // Strip per-target extension SHA records from ~/.claude/hypo-pkg.json. Surgical:
 // we only touch the entries for keys we actually removed, so a `--force-extensions`
@@ -424,7 +424,7 @@ const hookResult = removeHookFiles(claudeHooksDir, hookFiles, args.apply);
 const settingsResult = stripSettingsJson(claudeSettings, claudeHooksDir, hookMap, args.apply);
 const commandResult = removeCommands(args.apply, args.forceCommands);
 
-// Extensions (ADR 0024). Order matters: remove files first, then strip
+// Extensions. Order matters: remove files first, then strip
 // settings, then surgically clear the per-target SHA map. The SHA strip uses
 // removedKeys so a user-modified file we left in place keeps its recorded SHA
 // (doctor still has a baseline next run). Settings are path-based and run even

package/scripts/upgrade.mjs

@@ -20,7 +20,7 @@
  *                       the user-extensions companion sync (E4).
  *   --json              Output results as JSON
  *   --allow-downgrade   Override the guard that refuses to overwrite a NEWER
- *                       active install with an older package (ADR 0038)
+ *                       active install with an older package
  *   --allow-dual-install  Override the dual-install guard: register the Claude core
  *                       surface even though the Hypomnema plugin is also enabled
  *                       (knowingly accept the double-registration risk)
@@ -235,7 +235,7 @@ function checkSchemaVersion(hypoDir) {
 
 // Target-aware: the same core-hook integrity check runs against ~/.claude/hooks/
 // for the default claude target, and against ~/.codex/hooks/ when --codex is set
-// (ADR 0024). The function reads only — apply happens in applyHookFiles.
+// The function reads only (apply happens in applyHookFiles).
 function checkHookFiles(hooksDir) {
   const results = [];
 
@@ -465,6 +465,49 @@ function applyHypoignoreMigration(result) {
   return appended;
 }
 
+// ── .gitignore migration: mirror .cache/ into .gitignore (page-usage privacy) ─
+//
+// Legacy vaults may have a .gitignore that predates .cache/ (init now scaffolds
+// it, but old vaults were migrated only in .hypoignore). Without .cache/ in
+// .gitignore, the page-usage log could be committed. This mirrors the hypoignore
+// migration: idempotent append of the missing entry, no-op when already present
+// or when there is no .gitignore (the runtime logging guard fails closed for the
+// no-file case, so nothing leaks in the meantime).
+
+const GITIGNORE_REQUIRED_ENTRIES = [
+  {
+    pattern: '.cache/',
+    comment: '# Hypomnema runtime cache (page-usage log, session growth metrics)',
+  },
+];
+
+function checkGitignore(hypoDir) {
+  const path = join(hypoDir, '.gitignore');
+  if (!existsSync(path)) return { status: 'no-file', missing: [], path };
+  const content = readFileSync(path, 'utf-8');
+  const entries = new Set(
+    content
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith('#')),
+  );
+  const missing = GITIGNORE_REQUIRED_ENTRIES.filter((e) => !entries.has(e.pattern));
+  return { status: missing.length === 0 ? 'up-to-date' : 'needs-migration', missing, path };
+}
+
+function applyGitignoreMigration(result) {
+  if (result.status !== 'needs-migration') return [];
+  let content = readFileSync(result.path, 'utf-8');
+  if (!content.endsWith('\n')) content += '\n';
+  const appended = [];
+  for (const entry of result.missing) {
+    content += `\n${entry.comment}\n${entry.pattern}\n`;
+    appended.push(entry.pattern);
+  }
+  writeFileSync(result.path, content);
+  return appended;
+}
+
 function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = false } = {}) {
   const today = new Date().toISOString().slice(0, 10);
   const filename = `MIGRATION-v${toVersion}.md`;
@@ -473,15 +516,15 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   // Don't overwrite an existing report
   if (existsSync(dest)) return dest;
 
-  // v1 → v2 specific guidance for the ADR 0031 feedback classification bump.
-  // Other major jumps fall back to the generic body. ADR 0034 reserves the
-  // right to keep SCHEMA.md as user-owned (Option C); auto-stub of the 9 new
-  // fields is rejected because scope/tier/targets/sensitivity/reason/source
-  // are semantic decisions whose wrong defaults would project wrong behavior.
-  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the ADR
-  // 0031 feedback-field backfill that this body explains was introduced at 2.0
+  // v1 → v2 specific guidance for the feedback classification bump. Other major
+  // jumps fall back to the generic body. The schema deliberately keeps SCHEMA.md
+  // user-owned (Option C); auto-stub of the 9 new fields is rejected because
+  // scope/tier/targets/sensitivity/reason/source are semantic decisions whose
+  // wrong defaults would project wrong behavior.
+  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the
+  // feedback-field backfill that this body explains was introduced at 2.0
   // and still applies to a user landing on any later 2.x (e.g. 2.1's additive
-  // failure_type — FEAT-1). Keying on the exact target string would silently
+  // failure_type). Keying on the exact target string would silently
   // drop this guidance the moment the template minor moves.
   const fromV = parseVersion(fromVersion);
   const toV = parseVersion(toVersion);
@@ -489,8 +532,7 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   const specificBody = isV1ToV2
     ? `## What changed in SCHEMA 2.0
 
-ADR 0031 (\`projects/hypomnema/decisions/0031-feedback-as-sot-external-memory-projection.md\`)
-made \`feedback\` pages the single source of truth for behavior corrections and added
+This release made \`feedback\` pages the single source of truth for behavior corrections and added
 **9 hard-required frontmatter fields** for every \`feedback\` page:
 
 - \`status\` (active | superseded | archived)
@@ -510,8 +552,8 @@ that does not satisfy all four is rejected by both \`hypomnema lint\` and
 \`hypomnema feedback\` (see \`scripts/lint.mjs\` and \`scripts/feedback.mjs\`
 enforcement).
 
-ADR 0034 records this schema bump and the reasoning (semver-major because
-existing feedback pages without these fields now fail \`hypomnema lint\`).
+This schema bump is semver-major because existing feedback pages without these
+fields now fail \`hypomnema lint\`.
 
 ## Action items — existing wiki
 
@@ -799,7 +841,7 @@ function writePluginModeMetadata() {
 const args = parseArgs(process.argv);
 
 // Target paths. Claude is always checked; codex is checked only when --codex is set
-// (ADR 0024) so users without codex installed see no false drift.
+// so users without codex installed see no false drift.
 const claudeHooksDir = join(HOME, '.claude', 'hooks');
 const claudeSettingsPath = join(HOME, '.claude', 'settings.json');
 const codexHooksDir = join(HOME, '.codex', 'hooks');
@@ -850,6 +892,7 @@ const pkgJson = checkPkgJson();
 const commands = checkCommands();
 const oldHookRefs = checkOldHookNames(claudeSettingsPath);
 const hypoignore = checkHypoignore(args.hypoDir);
+const gitignore = checkGitignore(args.hypoDir);
 
 // when --codex is set, mirror the same core-hook checks against ~/.codex/
 // so `hypomnema upgrade --codex` reports drift symmetrically and `--apply --codex`
@@ -858,7 +901,7 @@ const hooksCodex = args.codex ? checkHookFiles(codexHooksDir) : null;
 const settingsCodex = args.codex ? checkSettingsJson(codexSettingsPath, codexHooksDir) : null;
 const oldHookRefsCodex = args.codex ? checkOldHookNames(codexSettingsPath) : null;
 
-// Extensions companion (ADR 0024). Read-only check; the apply
+// Extensions companion. Read-only check; the apply
 // happens below, AFTER applyCommands, so the per-target SHA map merges into the
 // hypo-pkg.json that applyCommands writes (rather than being clobbered by it).
 const extSettingsPath = claudeSettingsPath;
@@ -931,11 +974,12 @@ let appliedSettingsCodex = [];
 let appliedHookNameRenamesCodex = [];
 let appliedCommands = [];
 let appliedHypoignore = [];
+let appliedGitignore = [];
 let appliedExtensions = null;
 let appliedExtensionsCodex = null;
 
 if (args.apply) {
-  // Downgrade guard (ADR 0038, P): an `--apply` from an OLDER package than the
+  // Downgrade guard: an `--apply` from an OLDER package than the
   // active install would overwrite newer hooks (upgrade.mjs:287 copyFileSync) and
   // rewrite hypo-pkg.json to the older version. Refuse before the first mutation.
   // A dev workspace re-running its own --apply (incl. the post-commit sync hook)
@@ -1015,6 +1059,7 @@ if (args.apply) {
     }
   }
   appliedHypoignore = applyHypoignoreMigration(hypoignore);
+  appliedGitignore = applyGitignoreMigration(gitignore);
   // codex core hooks + settings + wiki-*→hypo-* rename mirror. Same order
   // as the claude side (rename first so subsequent hook copy can find renamed targets).
   if (args.codex) {
@@ -1090,6 +1135,7 @@ const hasDrift =
   pkgJsonDrift ||
   schemaDrift ||
   hypoignore.status === 'needs-migration' ||
+  gitignore.status === 'needs-migration' ||
   extDrift ||
   codexCoreDrift;
 
@@ -1110,6 +1156,7 @@ if (args.json) {
         commands,
         oldHookRefs,
         hypoignore,
+        gitignore,
         extensions: extCheck,
         extensionsCodex: extCheckCodex,
         // codex core mirror (null when --codex absent).
@@ -1123,6 +1170,7 @@ if (args.json) {
           hookNameRenames: appliedHookNameRenames,
           commands: appliedCommands,
           hypoignore: appliedHypoignore,
+          gitignore: appliedGitignore,
           extensions: appliedExtensions,
           extensionsCodex: appliedExtensionsCodex,
           hooksCodex: appliedHooksCodex,
@@ -1370,7 +1418,19 @@ if (hypoignore.status === 'no-file') {
   for (const e of hypoignore.missing) lines.push(`    + ${e.pattern}`);
 }
 
-// Extensions companion (ADR 0024; conflict/drift gating E3, #31). Shared by the
+// .gitignore migration (page-usage privacy: mirror .cache/ into .gitignore)
+if (gitignore.status === 'no-file') {
+  lines.push(`⚠ .gitignore        not found at ${gitignore.path} (init.mjs scaffolds this)`);
+} else if (gitignore.status === 'up-to-date') {
+  lines.push(`✓ .gitignore        required entries present`);
+} else {
+  lines.push(
+    `⚠ .gitignore        ${gitignore.missing.length} missing entry(s), run --apply to append:`,
+  );
+  for (const e of gitignore.missing) lines.push(`    + ${e.pattern}`);
+}
+
+// Extensions companion (conflict/drift gating E3, #31). Shared by the
 // claude target and, under --codex, the codex target (E4, #32) — the label keeps
 // the two blocks distinguishable in the report.
 function pushExtSummary(check, label) {
@@ -1425,6 +1485,7 @@ if (
   appliedHookNameRenames.length > 0 ||
   appliedCommands.length > 0 ||
   appliedHypoignore.length > 0 ||
+  appliedGitignore.length > 0 ||
   appliedHooksCodex.length > 0 ||
   appliedSettingsCodex.length > 0 ||
   appliedHookNameRenamesCodex.length > 0
@@ -1453,6 +1514,10 @@ if (
     lines.push(`✓ Appended .hypoignore entries (${appliedHypoignore.length}):`);
     for (const e of appliedHypoignore) lines.push(`    → ${e}`);
   }
+  if (appliedGitignore.length > 0) {
+    lines.push(`✓ Appended .gitignore entries (${appliedGitignore.length}):`);
+    for (const e of appliedGitignore) lines.push(`    → ${e}`);
+  }
   // codex-target applied actions (mirrors claude blocks above).
   if (appliedHookNameRenamesCodex.length > 0) {
     lines.push(`✓ Renamed legacy hook references (codex) (${appliedHookNameRenamesCodex.length}):`);
@@ -1508,6 +1573,7 @@ const totalDrift =
   (pkgJsonDrift ? 1 : 0) +
   (schemaDrift ? 1 : 0) +
   (hypoignore.status === 'needs-migration' ? hypoignore.missing.length : 0) +
+  (gitignore.status === 'needs-migration' ? gitignore.missing.length : 0) +
   extCheck.actions.filter(
     (a) => a.action === 'create' || a.action === 'update' || a.action === 'force-update',
   ).length +
@@ -1545,6 +1611,7 @@ if (totalDrift === 0) {
     (appliedPkgJson ? 1 : 0) +
     appliedHookNameRenames.length +
     appliedHypoignore.length +
+    appliedGitignore.length +
     appliedExtCount +
     appliedHooksCodex.length +
     appliedSettingsCodex.length +