hypomnema 1.5.0 → 1.6.0

package/scripts/uninstall.mjs

@@ -38,6 +38,8 @@ import {
   EXT_TYPES,
   CODEX_TYPES,
   readExtensionPkgStateNoMutate,
+  parseExtKey,
+  buildHookCommand,
 } from './lib/extensions.mjs';
 
 const HOME = homedir();
@@ -138,13 +140,23 @@ function stripExtensionsFromPkg(pkgPath, target, removedKeys, apply) {
   return changed;
 }
 
-// Remove hypo-ext-* hard-copies for one target (claude | codex). Mirrors
-// removeCommands' 3-way model: filesystem scan + per-target recorded SHA from
-// hypo-pkg.json#extensions[target] decides ownership. A file we never installed
-// (no recorded SHA) is left alone — that may be a foreign hypo-ext-* file the
-// user created by hand, never ours to delete. A user-modified file is preserved
-// unless --force-extensions; a symlink/non-regular target is always preserved
-// (force does not follow them, matching install/upgrade E3's guard).
+// Remove Hypomnema-installed extension hard-copies for one target (claude |
+// codex). Ownership is decided by the per-target recorded SHA map in
+// hypo-pkg.json#extensions[target]: we iterate the RECORDED KEYS (not a
+// filesystem+prefix scan) because the reverse-capture design decoupled the install filename from
+// the wiki `hypo-ext-*` storage name — a reverse-captured command installs as
+// `commands/mycmd.md`, which a prefix scan would never reach. The SHA map key
+// IS the install path relative to the target root, so it names every file we
+// own regardless of its filename.
+//
+// Safety (capture design §8): a recorded key comes from an on-disk JSON we do not
+// fully control, so each key is validated by `parseExtKey` to a single covered
+// `<type>/<safe-basename>` segment (no separators / traversal) before any
+// join/rm — a corrupt or malicious key can never delete outside the extension
+// directory. "Never delete unowned" holds via SHA MATCHING, not the prefix: a
+// file whose on-disk SHA differs from the recorded one is user-modified and
+// preserved unless --force-extensions; a symlink/non-regular target is always
+// preserved (force does not follow them, matching install/upgrade E3's guard).
 function removeExtensions(target, apply, force) {
   const targetRoot = target === 'codex' ? join(HOME, '.codex') : join(HOME, '.claude');
   const types = target === 'codex' ? CODEX_TYPES : EXT_TYPES;
@@ -158,37 +170,27 @@ function removeExtensions(target, apply, force) {
   const skippedUserModified = [];
   const skippedNonRegular = [];
 
-  for (const type of types) {
-    const typeDir = join(targetRoot, type);
-    if (!existsSync(typeDir)) continue;
-    let entries;
-    try {
-      entries = readdirSync(typeDir);
-    } catch {
+  for (const [key, recordedSHA] of Object.entries(recorded)) {
+    if (!recordedSHA) continue; // no ownership baseline → nothing to remove
+    const parsed = parseExtKey(key, types);
+    if (!parsed) continue; // untrusted / cross-target key → never join+rm
+    const fullPath = join(targetRoot, parsed.type, parsed.installFile);
+    if (!existsSync(fullPath)) continue; // already gone
+
+    if (!isRegularFile(fullPath)) {
+      // Refuse to follow symlinks/sockets even under --force-extensions.
+      skippedNonRegular.push(fullPath);
       continue;
     }
-    for (const fname of entries) {
-      if (!fname.startsWith(EXT_PREFIX)) continue;
-      const key = `${type}/${fname}`;
-      const recordedSHA = recorded[key];
-      if (!recordedSHA) continue; // not tracked by us → leave alone
-      const fullPath = join(typeDir, fname);
-
-      if (!isRegularFile(fullPath)) {
-        // Refuse to follow symlinks/sockets even under --force-extensions.
-        skippedNonRegular.push(fullPath);
-        continue;
-      }
-      const buf = readFileIfRegular(fullPath);
-      const sha = buf ? sha256(buf) : null;
-
-      if (sha === recordedSHA || force) {
-        if (apply) rmSync(fullPath);
-        removed.push(fullPath);
-        removedKeys.push(key);
-      } else {
-        skippedUserModified.push(fullPath);
-      }
+    const buf = readFileIfRegular(fullPath);
+    const sha = buf ? sha256(buf) : null;
+
+    if (sha === recordedSHA || force) {
+      if (apply) rmSync(fullPath);
+      removed.push(fullPath);
+      removedKeys.push(key);
+    } else {
+      skippedUserModified.push(fullPath);
     }
   }
   return { target, removed, removedKeys, skippedUserModified, skippedNonRegular };
@@ -226,12 +228,39 @@ function unprocessedExtensionTargetRemains(pkgPath, processedTargets) {
   return false;
 }
 
-// settings.json: strip groups whose command points to a hypo-ext-* path under
-// the target's hooks dir. Identity is path-based (plan §0 D1) — no hookMap needed
+// Build the set of settings.json commands owned by reverse-captured hooks that
+// install under their ORIGINAL name (not the hypo-ext-* storage name). The prefix
+// scan below only reaches hypo-ext-* commands; a captured hook registers as
+// `node $HOME/.claude/hooks/foo.mjs`, which no prefix would ever match. The
+// recorded per-target SHA map names every file we own, so its hooks `.mjs` keys
+// reconstruct exactly the commands we registered. Read WITHOUT mutation and while
+// the map is still whole. stripExtensionsFromPkg (which clears it) runs later.
+// Only `.mjs` keys are commands; the paired `.manifest.json` sidecar keys (which
+// parseExtKey also admits for hooks) are dropped by the extension check.
+function ownedHookCommands(pkgPath, target, hooksDir) {
+  const types = target === 'codex' ? CODEX_TYPES : EXT_TYPES;
+  const recorded = readExtensionPkgStateNoMutate(pkgPath, target);
+  const commands = new Set();
+  for (const key of Object.keys(recorded)) {
+    const parsed = parseExtKey(key, types);
+    if (!parsed || parsed.type !== 'hooks') continue;
+    if (!parsed.installFile.endsWith('.mjs')) continue;
+    commands.add(buildHookCommand(hooksDir, parsed.installFile));
+  }
+  return commands;
+}
+
+// settings.json: strip groups whose command is one of ours under the target's
+// hooks dir. Ownership is the UNION of two path-based signals (plan §0 D1, P2):
+// the hypo-ext-* command prefix (catches wiki-authored hooks and hypo-ext-*
+// leftovers whose recorded key was already cleared by a partial uninstall) and
+// the recorded owned-command set (`ownedCommands`, catches reverse-captured hooks
+// registered under their original name, which carry no hypo-ext-* marker). Both
+// branches are needed, so this is a union, not a replacement. No hookMap needed
 // because ext hooks are never enumerated there. Mixed groups (foreign hook +
 // ours) keep the foreign hook; ours-only groups are dropped entirely. Mirrors
 // stripSettingsJson's flatMap pattern so other-plugin invariants (§7.3) hold.
-function stripExtensionSettings(settingsPath, hooksDir, apply) {
+function stripExtensionSettings(settingsPath, hooksDir, apply, ownedCommands = new Set()) {
   if (!existsSync(settingsPath)) return { stripped: [] };
   let settings;
   try {
@@ -243,7 +272,10 @@ function stripExtensionSettings(settingsPath, hooksDir, apply) {
 
   const cmdPrefix = `node ${hooksDir.replace(HOME, '$HOME')}/${EXT_PREFIX}`;
   const isExtHook = (h) =>
-    h && h.type === 'command' && typeof h.command === 'string' && h.command.startsWith(cmdPrefix);
+    h &&
+    h.type === 'command' &&
+    typeof h.command === 'string' &&
+    (h.command.startsWith(cmdPrefix) || ownedCommands.has(h.command));
 
   const stripped = [];
   let changed = false;
@@ -432,7 +464,12 @@ const commandResult = removeCommands(args.apply, args.forceCommands);
 // hook copy was deleted by hand (force-commands legacy state).
 const pkgJsonPath = join(HOME, '.claude', 'hypo-pkg.json');
 const claudeExtResult = removeExtensions('claude', args.apply, args.forceExtensions);
-const claudeExtSettings = stripExtensionSettings(claudeSettings, claudeHooksDir, args.apply);
+const claudeExtSettings = stripExtensionSettings(
+  claudeSettings,
+  claudeHooksDir,
+  args.apply,
+  ownedHookCommands(pkgJsonPath, 'claude', claudeHooksDir),
+);
 
 let codexHookResult = { removed: [], missing: [] };
 let codexSettingsResult = { stripped: [] };
@@ -452,7 +489,12 @@ if (args.codex) {
   codexHookResult = removeHookFiles(codexHooksDir, hookFiles, args.apply);
   codexSettingsResult = stripSettingsJson(codexSettings, codexHooksDir, hookMap, args.apply);
   codexExtResult = removeExtensions('codex', args.apply, args.forceExtensions);
-  codexExtSettings = stripExtensionSettings(codexSettings, codexHooksDir, args.apply);
+  codexExtSettings = stripExtensionSettings(
+    codexSettings,
+    codexHooksDir,
+    args.apply,
+    ownedHookCommands(pkgJsonPath, 'codex', codexHooksDir),
+  );
 }
 
 // Surgical per-target ext SHA strip — only for files we actually removed.

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]].

package/skills/ingest/SKILL.md

@@ -104,4 +104,4 @@ Append an ingest entry to `<wiki-root>/log.md`:
 
 ---
 
-> **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/lint/SKILL.md

@@ -56,4 +56,4 @@ For **missing required fields** (`title`, `type`): open the affected files and h
 
 ---
 
-> **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/query/SKILL.md

@@ -59,4 +59,4 @@ If zero results are returned, say so and offer to broaden the search or suggest
 
 ---
 
-> **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/verify/SKILL.md

@@ -93,4 +93,4 @@ updated: <today YYYY-MM-DD>
 
 ---
 
-> **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/templates/hypo-config.md

@@ -1,7 +1,7 @@
 ---
 title: Hypomnema Config
 type: config
-version: "1.5.0"
+version: "1.6.0"
 created: YYYY-MM-DD
 ---
 

package/templates/hypo-guide.md

@@ -225,7 +225,7 @@ ADRs are immutable once accepted. Mark deprecated/superseded but never edit cont
 
 Hypomnema v1.1.0 ships an **autonomy score** so you can see whether the wiki is actually being used per session, rather than just trusting that it is.
 
-- **Citation:** when a response uses a wiki page, link it inline as `[[page-slug]]`. The audit script counts citations as one signal of "the wiki was actually consulted".
+- **Citation:** when a response uses a wiki page, link it inline as `[[page-slug]]` to keep it connected in the graph. (The audit score is based on the tool and command usage below, not on these inline citations.)
 - **Tools that count:** `Grep`, `WebSearch`, `WebFetch`, and any `/hypo:query` / `/hypo:ingest` / `/hypo:feedback` invocation in the transcript.
 - **Classification (heuristic v0):**
   - `normal` — at least one search, no missed URL ingests