hypomnema 1.5.0 → 1.5.1

package/hooks/hypo-shared.mjs

@@ -284,17 +284,22 @@ export function sessionLogScopePath(hypoDir, project, date) {
  * True if `content` carries a today-dated `## [date] session | <project>` entry
  * in log.md.
  *
- * Bounded with an explicit `(?=\s|$)` lookahead, NOT `\b`: a regex word boundary
- * matches between word and non-word chars, so `\b` after "foo" still matches in
- * "foo-bar" (hyphen is non-word). The canonical log format always separates the
- * project slug from anything that follows by whitespace or end-of-line, so the
- * lookahead correctly rejects "session | foo-bar" when looking for "foo".
- * (Was a pre-existing bug in sessionCloseFileStatus that the helper extraction
- * inherited.)
+ * Bounded with an explicit `(?=[\s:]|$)` lookahead, NOT `\b`: a regex word
+ * boundary matches between word and non-word chars, so `\b` after "foo" still
+ * matches in "foo-bar" (hyphen is non-word). The canonical log format separates
+ * the project slug from anything that follows by whitespace, a colon, or
+ * end-of-line, so the lookahead correctly rejects "session | foo-bar" when
+ * looking for "foo". Both delimiters are canonical: the derive path
+ * (rootLogEntry) emits `<project> — <title>` (space), while the dominant
+ * hand-written convention is `<project>: <title>` (colon, since the tone rule
+ * banned the em dash). The colon must be accepted: without it, a close whose
+ * only log.md evidence used the colon form was misread as "stale" and blocked
+ * non-deterministically. (Was a pre-existing boundary bug in
+ * sessionCloseFileStatus that the helper extraction inherited.)
  */
 export function hasLogEntry(content, date, project) {
   return new RegExp(
-    '^## \\[' + escapeRegExp(date) + '\\] session \\| ' + escapeRegExp(project) + '(?=\\s|$)',
+    '^## \\[' + escapeRegExp(date) + '\\] session \\| ' + escapeRegExp(project) + '(?=[\\s:]|$)',
     'm',
   ).test(content || '');
 }
@@ -352,6 +357,139 @@ function parseFrontmatterField(content, key) {
     .replace(/^['"]|['"]$/g, '');
 }
 
+// ── freshness: overdue verify_by_date predicate + STALE injection marker ─────
+// Authority is doctor.mjs:487-491 (D1). Same characters, same meaning: only a
+// well-formed ISO date strictly before `today` is overdue. verify_by (the
+// natural-language question) is never a date and is never consulted here.
+// today is caller-supplied and must use the UTC convention (new Date()
+// .toISOString().slice(0,10)) so this set matches doctor's.
+export function isOverdueDate(dateStr, today) {
+  return /^\d{4}-\d{2}-\d{2}$/.test(dateStr) && dateStr < today;
+}
+
+// Compute the injection marker for a page's raw content. Returns
+// `[STALE verify_by_date=YYYY-MM-DD]` when overdue, otherwise an empty string
+// (so non-targets pass through unchanged). Callers prepend the non-empty result
+// at injection time.
+//
+// The value read here must be normalized exactly as scripts/lib/frontmatter.mjs
+// does (doctor's parser), so the overdue set stays char-identical to doctor.mjs.
+// In particular it strips a trailing YAML inline comment (`2020-01-01 # note`):
+// the plain parseFrontmatterField does not, which would silently miss dates
+// doctor flags overdue. Top-level line only (skip indented / list entries),
+// first-wins, strip comment, then strip surrounding quotes.
+export function staleMarkerFor(rawContent, today) {
+  const m = rawContent.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return '';
+  let value = null;
+  for (const line of m[1].split(/\r?\n/)) {
+    if (/^\s/.test(line) || /^-(\s|$)/.test(line)) continue; // nested / list item
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    if (line.slice(0, idx).trim() !== 'verify_by_date') continue; // key match (idx: tolerates `key : v`)
+    value = line
+      .slice(idx + 1)
+      .trim()
+      .replace(/\s+#.*$/, '')
+      .replace(/^["']|["']$/g, '');
+    break; // first-wins
+  }
+  return value && isOverdueDate(value, today) ? `[STALE verify_by_date=${value}]` : '';
+}
+
+// ── page-usage logging: commit-coverage guard + append (B, D6) ───────────────
+// Logging which pages lookup injects is observability, never an injection path.
+// The log lives at .cache/page-usage.jsonl and must never be committed. Before
+// any append, prove that file cannot be staged/committed: it must be covered by
+// BOTH git's ignore rules (check-ignore) AND .hypoignore (which is what gates
+// hypo-auto-stage and commitWikiChanges). Missing either signal, or any error
+// (no git, timeout, non-repo), returns false so nothing is written (fail-closed
+// logging). Injection stays fail-open and is unaffected. The verdict is cached
+// per session (keyed by session_id plus a vault-path hash so two vaults in one
+// session can't cross-contaminate) so git runs at most once per session.
+export const PAGE_USAGE_REL = '.cache/page-usage.jsonl';
+
+export function pageUsageGuardCachePath(sessionId, hypoDir) {
+  const safe = String(sessionId || 'default').replace(/[^A-Za-z0-9._-]/g, '_') || 'default';
+  // djb2 over the vault path so the cache key is per-(session, vault).
+  let h = 5381;
+  const s = String(hypoDir || '');
+  for (let i = 0; i < s.length; i++) h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
+  return join(tmpdir(), `hypo-pageusage-guard-${safe}-${h.toString(36)}.json`);
+}
+
+export function pageUsageLoggingAllowed(hypoDir, sessionId) {
+  // The load-bearing commit gate is .hypoignore: it is what hypo-auto-stage and
+  // commitWikiChanges actually filter on. Re-check it FRESH on every call (it is
+  // cheap, no subprocess) so that if coverage is removed mid-session the guard
+  // flips closed immediately and can never leave logging armed against a
+  // now-committable file. Only the expensive git check-ignore probe is cached
+  // per session. Any error on either signal fails closed.
+  let hypoIgnored = false;
+  try {
+    const target = join(hypoDir, PAGE_USAGE_REL);
+    const patterns = loadHypoIgnore(hypoDir);
+    hypoIgnored = patterns.length > 0 && isIgnored(target, hypoDir, patterns);
+  } catch {
+    hypoIgnored = false;
+  }
+  if (!hypoIgnored) return false;
+
+  return gitIgnoresPageUsageCached(hypoDir, sessionId);
+}
+
+// git check-ignore is the belt signal (defends a manual `git add`); it spawns a
+// subprocess, so cache its result per session. The verdict cached here is only
+// the git signal, never the composite allow decision, so the fresh .hypoignore
+// re-check above always still runs.
+function gitIgnoresPageUsageCached(hypoDir, sessionId) {
+  const cachePath = pageUsageGuardCachePath(sessionId, hypoDir);
+  try {
+    if (existsSync(cachePath)) {
+      const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+      if (typeof cached.gitIgnored === 'boolean') return cached.gitIgnored;
+    }
+  } catch {
+    // corrupt cache → recompute below
+  }
+
+  let gitIgnored = false;
+  try {
+    gitIgnored =
+      spawnSync('git', ['-C', hypoDir, 'check-ignore', '-q', '--', PAGE_USAGE_REL], {
+        timeout: 2000,
+      }).status === 0;
+  } catch {
+    gitIgnored = false;
+  }
+
+  try {
+    writeFileSync(cachePath, JSON.stringify({ gitIgnored }));
+  } catch {
+    // cache write failure is non-fatal; the git probe just reruns next prompt
+  }
+  return gitIgnored;
+}
+
+// Append one JSONL record per injected slug to .cache/page-usage.jsonl. Callers
+// MUST gate this behind pageUsageLoggingAllowed first. Fully fail-open: any error
+// (mkdir, disk, serialization) is swallowed so a logging failure never disturbs
+// the lookup injection that already happened (mirrors hypo-session-record).
+export function recordLookupUsage(hypoDir, { sessionId = null, slugs = [] } = {}) {
+  try {
+    if (!Array.isArray(slugs) || slugs.length === 0) return;
+    const target = join(hypoDir, PAGE_USAGE_REL);
+    mkdirSync(join(hypoDir, '.cache'), { recursive: true });
+    const ts = new Date().toISOString();
+    const lines = slugs
+      .map((slug) => JSON.stringify({ ts, session_id: sessionId ?? null, slug, source: 'lookup' }))
+      .join('\n');
+    appendFileSync(target, lines + '\n');
+  } catch {
+    // logging is observability; never let it break injection (fail-open)
+  }
+}
+
 // ── cwd ↔ project matcher ────────────────────────────────────────────────────
 // Hand-synced with scripts/lib/wd-match.mjs: hooks deploy to ~/.claude/hooks/
 // without scripts/, so this cannot import the lib and must mirror it. Keep the
@@ -787,13 +925,20 @@ function closeCandidateSlugs(hypoDir, dates) {
       content = '';
     }
     for (const d of dates) {
-      const re = new RegExp('^## \\[' + escapeRegExp(d) + '\\] session \\| (\\S+)', 'gm');
+      // Capture the slug up to the first whitespace OR colon so both canonical
+      // log delimiters resolve to the same bare slug: `session | beta — t` and
+      // `session | beta: t` both yield `beta`. This parser shares the
+      // colon-delimiter contract with hasLogEntry, so a colon-form entry for a
+      // real project is a close candidate, not a ghost. `[^\s:]+` cannot span
+      // the colon, so a stale/typo heading still yields a token that fails the
+      // on-disk directory gate below.
+      const re = new RegExp('^## \\[' + escapeRegExp(d) + '\\] session \\| ([^\\s:]+)', 'gm');
       for (const m of content.matchAll(re)) {
-        // B-1: only real projects are close candidates. A malformed log heading
-        // (`## [d] session | hypomnema:`) or a stale slug yields a ghost token
-        // that no longer maps to a `projects/<slug>/` directory — gating on disk
-        // keeps it out of the dangling-close set. Directory (not bare-exists)
-        // mirrors the apply-path project check (crystallize.mjs:193).
+        // B-1: only real projects are close candidates. A stale or misspelled
+        // slug yields a token that no longer maps to a `projects/<slug>/`
+        // directory — gating on disk keeps it out of the dangling-close set.
+        // Directory (not bare-exists) mirrors the apply-path project check
+        // (crystallize.mjs:193).
         const dir = join(projectsDir, m[1]);
         if (existsSync(dir) && statSync(dir).isDirectory()) slugs.add(m[1]);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",

package/scripts/crystallize.mjs

@@ -73,6 +73,7 @@ import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
 import { collectPagesCrystallize, extractWikilinks } from './lib/wikilink.mjs';
+import { aggregateColdCandidates } from './lib/page-usage.mjs';
 import { isValidProjectName } from './lib/project-create.mjs';
 import { appendPendingTags, checkForbidden } from './lib/schema-vocab.mjs';
 import {
@@ -88,6 +89,8 @@ import {
   sessionLogReadCandidates,
   sessionLogScopePath,
   rootLogEntry,
+  hasSessionLogHeading,
+  hasLogEntry,
   resolveTranscriptBySessionId,
   hasUserCloseSignal,
   commitWikiChanges,
@@ -753,21 +756,49 @@ function applySessionClose(args) {
   }
   const date = payload.date || todayLocal();
 
-  // B-1 derive precondition: when `log` is omitted, apply reconstructs the root
-  // log.md entry from THIS close's sessionLog heading. If sessionLog.entry has no
-  // `## [<date>] …` heading there is nothing to derive — and on a same-day SECOND
-  // close the date-level freshness verifier would still pass on the earlier
-  // close's entry, so the no-write would slip through as ok:true. Fail loud here,
-  // before any writes (codex pre-commit review).
-  if (
-    !payload.log &&
-    !new RegExp(`^#{1,6} \\[${date}\\]`, 'm').test(payload.sessionLog.entry || '')
-  ) {
-    const msg =
-      `payload.sessionLog.entry has no "## [${date}] …" heading to derive the log.md ` +
-      `entry from. Give it a dated heading, or supply payload.log explicitly.`;
-    console.log(args.json ? JSON.stringify({ ok: false, error: msg }, null, 2) : `✗ ${msg}`);
+  // Pre-apply freshness-contract gate: the post-apply verification holds
+  // sessionCloseFileStatus's hasSessionLogHeading / hasLogEntry as the
+  // definition of "closed today". Enforce that SAME contract on the payload
+  // BEFORE writing a byte, so a heading the gate won't recognize is rejected
+  // here as a format mismatch — not written and then misdiagnosed downstream as
+  // "stale" (the "not updated" vs "format mismatch" conflation). All checks
+  // exit 1 with stage='pre-apply-verification' and leave the tree untouched.
+  const failPreApply = (msg) => {
+    console.log(
+      args.json
+        ? JSON.stringify({ ok: false, stage: 'pre-apply-verification', error: msg }, null, 2)
+        : `✗ ${msg}`,
+    );
     process.exit(1);
+  };
+  // (a) The session-log entry must carry a dated `## [<date>] …` ATX heading. The
+  // post-apply gate checks the session-log file for exactly this heading, so a
+  // headingless entry would write then false-fail as "stale". This also doubles
+  // as the B-1 derive precondition: when `log` is omitted the root log.md entry
+  // is reconstructed from THIS heading, and on a same-day SECOND close the
+  // date-level verifier would still pass on the earlier entry, so a no-derive
+  // would slip through as ok:true. The `!payload.log` branch keeps the original
+  // derive-specific wording (a test asserts it).
+  if (!hasSessionLogHeading(payload.sessionLog.entry || '', date)) {
+    failPreApply(
+      !payload.log
+        ? `payload.sessionLog.entry has no "## [${date}] …" heading to derive the log.md ` +
+            `entry from. Give it a dated heading, or supply payload.log explicitly.`
+        : `payload.sessionLog.entry has no "## [${date}] …" heading. The close gate ` +
+            `identifies a session-log by its dated ATX heading; give the entry a ` +
+            `"## [${date}] <title>" heading (the brackets are required).`,
+    );
+  }
+  // (b) An explicit payload.log entry must match the canonical
+  // `## [<date>] session | <project>` line the gate looks for (colon or space
+  // delimiter after the slug). Otherwise the write lands but post-apply
+  // verification reports log.md as stale. When `log` is omitted the line is
+  // derived canonically (rootLogEntry) so this cannot mismatch.
+  if (payload.log && !hasLogEntry(payload.log.entry || '', date, project)) {
+    failPreApply(
+      `payload.log.entry has no "## [${date}] session | ${project}" heading that the ` +
+        `close gate recognizes. Fix the entry heading, or omit payload.log to derive it.`,
+    );
   }
 
   // Preflight: lint the wiki BEFORE writing any payload bytes. If lint
@@ -1315,8 +1346,12 @@ const synthesisGroups = Object.entries(tagGroups)
   .sort((a, b) => b[1].length - a[1].length)
   .map(([tag, pages]) => ({ tag, pages }));
 
+// Lookup-cold candidates (B): pages with inbound wikilinks that lookup has not
+// injected within the recency window. Advisory only, never gates, never mutates.
+const coldCandidates = aggregateColdCandidates(args.hypoDir, { ignorePatterns });
+
 if (args.json) {
-  console.log(JSON.stringify({ synthesisGroups, unlinked, drafts }, null, 2));
+  console.log(JSON.stringify({ synthesisGroups, unlinked, drafts, coldCandidates }, null, 2));
   process.exit(0);
 }
 
@@ -1346,6 +1381,25 @@ if (drafts.length > 0) {
   console.log('');
 }
 
+// Advisory (non-gating): pages the graph treats as live but lookup has not
+// injected recently. Held until enough page-usage history accrues.
+if (coldCandidates.status === 'ok' && coldCandidates.candidates.length > 0) {
+  found = true;
+  console.log(
+    `Lookup-cold pages (${coldCandidates.candidates.length}), inbound links but not injected recently:`,
+  );
+  for (const p of coldCandidates.candidates) console.log(`  [[${p.slug}]] (${p.title})`);
+  console.log('');
+} else if (
+  coldCandidates.status === 'insufficient-data' &&
+  coldCandidates.reason === 'span-too-short'
+) {
+  // Only surface the "held" notice once a log is actually accruing (span under
+  // the cold-start window). A vault with no log at all stays silent so this
+  // advisory never becomes permanent noise on every crystallize run.
+  console.log('Lookup-cold scan held: not enough page-usage history yet (advisory).\n');
+}
+
 if (!found) {
   console.log('✓ No crystallization candidates found — Hypomnema looks well-connected.');
 }

package/scripts/lib/page-usage.mjs

@@ -0,0 +1,141 @@
+// page-usage.mjs: read-only aggregation over .cache/page-usage.jsonl (B3)
+//
+// The lookup hook appends one JSONL record per injected page slug (see
+// hooks/hypo-shared.mjs recordLookupUsage). This lib reads that log and derives
+// "lookup-cold candidates": pages that have inbound wikilinks (so the graph
+// treats them as live) but have not been injected by lookup within a recency
+// window. It writes nothing and is only invoked from scripts (crystallize), so
+// it never touches the per-prompt hook hot path.
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { collectPagesCrystallize, extractWikilinks, slugForms } from './wikilink.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+const PAGE_USAGE_REL = '.cache/page-usage.jsonl';
+const DAY_MS = 86400000;
+
+// The distinct link forms a slug may appear as in a [[wikilink]] or in the log:
+// its full path, its basename, and (when nested) the path minus its first
+// segment. Matching by form-set intersection bridges the gap between the log's
+// index-matched slug form and the reverse index's [[wikilink]] form.
+function formSet(slug) {
+  const f = slugForms(slug);
+  const s = new Set([f.full, f.bare]);
+  if (f.dirRel) s.add(f.dirRel);
+  return s;
+}
+
+function intersects(a, b) {
+  for (const x of a) if (b.has(x)) return true;
+  return false;
+}
+
+// Read every record from the usage log, skipping malformed lines. Returns [] if
+// the log is absent or unreadable (fail-soft: aggregation is advisory).
+export function readPageUsage(hypoDir) {
+  const path = join(hypoDir, PAGE_USAGE_REL);
+  if (!existsSync(path)) return [];
+  let text;
+  try {
+    text = readFileSync(path, 'utf-8');
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      // Only keep plain objects. A bare `null`, number, string, or array is
+      // valid JSON but not a record; keeping it would crash the field access in
+      // aggregateColdCandidates (and crystallize calls that outside a try).
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+      // malformed line → skip (log is append-only and may be partially written)
+    }
+  }
+  return records;
+}
+
+// Derive lookup-cold candidates. Guards against cold-start: if there are no
+// records, or the observed log span is shorter than minLogSpanDays, returns
+// { status: 'insufficient-data' } so a fresh log doesn't flag the whole vault.
+// Otherwise returns { status: 'ok', candidates: [{ slug, title }] } for pages
+// that have >= 1 inbound wikilink from another page yet have not been logged
+// within the last thresholdDays.
+export function aggregateColdCandidates(
+  hypoDir,
+  { thresholdDays = 90, minLogSpanDays = 14, now = Date.now(), ignorePatterns = [] } = {},
+) {
+  const records = readPageUsage(hypoDir);
+  if (records.length === 0) return { status: 'insufficient-data', reason: 'no-records' };
+
+  const times = records.map((r) => Date.parse(r.ts)).filter((t) => Number.isFinite(t));
+  if (times.length === 0) return { status: 'insufficient-data', reason: 'no-timestamps' };
+  const span = Math.max(...times) - Math.min(...times);
+  if (span < minLogSpanDays * DAY_MS) {
+    return { status: 'insufficient-data', reason: 'span-too-short' };
+  }
+
+  // Forms of every slug logged within the recency window.
+  const recentCutoff = now - thresholdDays * DAY_MS;
+  const recentForms = new Set();
+  for (const r of records) {
+    const t = Date.parse(r.ts);
+    if (!Number.isFinite(t) || t < recentCutoff) continue;
+    if (typeof r.slug !== 'string' || !r.slug) continue;
+    for (const form of formSet(r.slug)) recentForms.add(form);
+  }
+
+  // Build the page list with slug, title, forms, and outbound links.
+  const pagesDir = join(hypoDir, 'pages');
+  const pageList = [];
+  for (const { path, rel } of collectPagesCrystallize(pagesDir, hypoDir, ignorePatterns)) {
+    let content;
+    try {
+      content = readFileSync(path, 'utf-8');
+    } catch {
+      continue;
+    }
+    const fm = parseFrontmatter(content);
+    if (!fm) continue;
+    const slug = rel.replace(/\.md$/, '');
+    const body = content.replace(/^---[\s\S]*?---/, '');
+    pageList.push({
+      slug,
+      title: fm.title || slug,
+      forms: formSet(slug),
+      links: extractWikilinks(body),
+    });
+  }
+
+  // Reverse index: which page slugs receive >= 1 inbound link from another page.
+  const formOwners = new Map(); // form → Set<page slug>
+  for (const p of pageList) {
+    for (const form of p.forms) {
+      if (!formOwners.has(form)) formOwners.set(form, new Set());
+      formOwners.get(form).add(p.slug);
+    }
+  }
+  const hasInbound = new Set();
+  for (const p of pageList) {
+    for (const link of p.links) {
+      const targets = new Set();
+      for (const form of formSet(link)) {
+        const owners = formOwners.get(form);
+        if (owners) for (const o of owners) targets.add(o);
+      }
+      for (const t of targets) if (t !== p.slug) hasInbound.add(t);
+    }
+  }
+
+  const candidates = pageList
+    .filter((p) => hasInbound.has(p.slug) && !intersects(p.forms, recentForms))
+    .map((p) => ({ slug: p.slug, title: p.title }));
+
+  return { status: 'ok', candidates };
+}

package/scripts/upgrade.mjs

@@ -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`;
@@ -849,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`
@@ -930,6 +974,7 @@ let appliedSettingsCodex = [];
 let appliedHookNameRenamesCodex = [];
 let appliedCommands = [];
 let appliedHypoignore = [];
+let appliedGitignore = [];
 let appliedExtensions = null;
 let appliedExtensionsCodex = null;
 
@@ -1014,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) {
@@ -1089,6 +1135,7 @@ const hasDrift =
   pkgJsonDrift ||
   schemaDrift ||
   hypoignore.status === 'needs-migration' ||
+  gitignore.status === 'needs-migration' ||
   extDrift ||
   codexCoreDrift;
 
@@ -1109,6 +1156,7 @@ if (args.json) {
         commands,
         oldHookRefs,
         hypoignore,
+        gitignore,
         extensions: extCheck,
         extensionsCodex: extCheckCodex,
         // codex core mirror (null when --codex absent).
@@ -1122,6 +1170,7 @@ if (args.json) {
           hookNameRenames: appliedHookNameRenames,
           commands: appliedCommands,
           hypoignore: appliedHypoignore,
+          gitignore: appliedGitignore,
           extensions: appliedExtensions,
           extensionsCodex: appliedExtensionsCodex,
           hooksCodex: appliedHooksCodex,
@@ -1369,6 +1418,18 @@ if (hypoignore.status === 'no-file') {
   for (const e of hypoignore.missing) lines.push(`    + ${e.pattern}`);
 }
 
+// .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.
@@ -1424,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
@@ -1452,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}):`);
@@ -1507,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 +
@@ -1544,6 +1611,7 @@ if (totalDrift === 0) {
     (appliedPkgJson ? 1 : 0) +
     appliedHookNameRenames.length +
     appliedHypoignore.length +
+    appliedGitignore.length +
     appliedExtCount +
     appliedHooksCodex.length +
     appliedSettingsCodex.length +

package/skills/crystallize/SKILL.md

@@ -92,7 +92,9 @@ main conversation id. Passing the wrong id causes `markerWritten: false` with
 `markerSkipReason: "transcript-unresolved"` or `"no-user-close-signal"`: the
 5 mandatory files are written (ok: true) but the Stop-chain marker is withheld,
 so the session is not actually closed and the Stop hook re-prompts. The correct
-id comes from the `[WIKI_AUTOCLOSE]` block reason or `$CLAUDE_SESSION_ID`.
+id comes from the `[WIKI_AUTOCLOSE]` block reason or the injected
+`$CLAUDE_CODE_SESSION_ID` (accept the legacy spelling via
+`${CLAUDE_CODE_SESSION_ID:-$CLAUDE_SESSION_ID}`).
 
 Once it passes, report each item with ✓:
 - ✓ session-state.md
@@ -100,11 +102,15 @@ Once it passes, report each item with ✓:
 - ✓ session-log entry
 - ✓ open-questions (or skipped if unchanged)
 - ✓ log.md entry
-- **marker written?** (required, if `--apply-session-close --session-id` was used): check `markerWritten` in the JSON output. If `true`, report "session-close marker written." If `false`, do NOT declare the session closed or complete. Instead report: "Files applied and verified (ok: true), but the session-close marker was not written (reason: `<markerSkipReason>`). The Stop-chain is still active. Re-run with the correct main-conversation `--session-id`."
+- **marker written?** (required, if `--apply-session-close --session-id` was used): check `markerWritten` in the JSON output. If `true`, report "session-close marker written." If `false`, do NOT declare the session closed or complete; recover per the `markerSkipReason` branch below.
 
 If `markerWritten: true` (or `--session-id` was not passed), ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
 
-If `markerWritten: false`, do NOT say "session closed." Surface the skip reason and instruct a re-run with the correct main-conversation `--session-id` (see the bullet above) before treating the session as closed.
+If `markerWritten: false`, do NOT say "session closed." Branch on `markerSkipReason`:
+
+- `no-user-close-signal`: files applied cleanly and the transcript resolved, but it carries no close phrase the gate recognizes (the user's close wording fell outside the close-signal set, e.g. "세션 마무리까지 진행해줘" / "세션 마무리 진행"). Re-running the same id will not help. Confirm intent once with `AskUserQuestion` (header "세션", one option **세션 마무리**); if the user picks it, that answer is a recognized close signal, so re-run the same `--apply-session-close … --session-id` command (idempotent no-op writes; the marker lands). If the user declines, leave the session unmarked. Do NOT change the close-signal matcher.
+- `transcript-unresolved` (wrong / background id): report "Files applied and verified (ok: true), but the marker was not written (reason: `<markerSkipReason>`). The Stop-chain is still active. Re-run with the correct main-conversation `--session-id`."
+- any other reason (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface it verbatim and resolve the underlying blocker before re-running.
 
 ---
 
@@ -141,4 +147,4 @@ evidence_strength: inferred
 
 ---
 
-> **Citation convention.** When you reference a wiki page in your response, link it as `[[page-slug]]`. The observability audit counts citations toward the autonomy score — see [[pages/observability/_index]] (run `/hypo:audit` to inspect).
+> **Citation convention.** When you reference a wiki page in your response, link it as `[[page-slug]]` so it stays connected in the graph. The observability audit scores sessions on search / ingest / feedback activity (recorded by `hypo-session-record`), not on these inline citations; run `/hypo:audit` to inspect and see [[pages/observability/_index]].

package/skills/graph/SKILL.md

@@ -55,4 +55,4 @@ If the graph has 0 edges, note that no `[[wikilinks]]` were found between pages.
 
 ---
 
-> **Citation convention.** When you reference a wiki page in your response, link it as `[[page-slug]]`. The observability audit counts citations toward the autonomy score — see [[pages/observability/_index]] (run `/hypo:audit` to inspect).
+> **Citation convention.** When you reference a wiki page in your response, link it as `[[page-slug]]` so it stays connected in the graph. The observability audit scores sessions on search / ingest / feedback activity (recorded by `hypo-session-record`), not on these inline citations; run `/hypo:audit` to inspect and see [[pages/observability/_index]].