hypomnema 1.7.2 → 1.7.4

package/scripts/rename.mjs

@@ -48,11 +48,22 @@ import {
   chmodSync,
   rmSync,
 } from 'fs';
-import { join, basename, dirname, normalize, isAbsolute, sep } from 'path';
+import { join, basename, dirname, normalize, isAbsolute } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
-import { collectPagesRename, slugForms } from './lib/wikilink.mjs';
+import { collectPagesRename } from './lib/wikilink.mjs';
 import { RENAME_MARKER_REL, renameMarkerPath, readRenameMarker } from './lib/rename-marker.mjs';
+import {
+  dirRelForm,
+  buildFormIndex,
+  classifyTarget,
+  newTargetFor,
+  maskNonWikilinkRegions,
+  splitLinkBody,
+  preservationClass,
+  isPreservedSource,
+  realContainedInVault,
+} from './lib/slug-resolver.mjs';
 
 // ── arg parsing ───────────────────────────────────────────────────────────────
 
@@ -69,108 +80,16 @@ function parseArgs(argv) {
   return args;
 }
 
-// ── preservation class of a link-source path ───────────────────────────────────
-// Two distinct reasons a file is normally skipped as a link SOURCE, kept separate
-// because directory mode treats them differently (codex design BLOCKER):
-//
-//   'timerecord' — append-only snapshots (journal / session-log / weekly / archive
-//      / postmortems + root log.md). Rewriting a [[old]] inside a past entry would
-//      falsify that moment. BUT a directory move relocates the whole subtree, so a
-//      time-record INSIDE the moved subtree that links a moving sibling must update
-//      that intra-subtree path label (the page genuinely moved); see runDirectory.
-//
-//   'sources'    — sources/* immutable CAPTURED material. Never rewritten, not even
-//      inside a moved subtree: a directory move must not claim ownership over the
-//      bytes of an external source we transcribed verbatim.
-//
-// Matches a path SEGMENT so `pages/journal/x.md` and `projects/p/session-log/y.md`
-// both qualify. Returns null for ordinary live pages.
-function preservationClass(rel) {
-  const p = rel.replace(/\\/g, '/');
-  if (/(^|\/)sources(\/|$)/.test(p)) return 'sources';
-  if (p === 'log.md') return 'timerecord';
-  if (/(^|\/)(journal|session-log|weekly|archive|postmortems)(\/|$)/.test(p)) return 'timerecord';
-  return null;
-}
-
-// Single-page mode preserves BOTH classes as link sources (unchanged behavior): a
-// rename elsewhere in the vault must never churn a frozen snapshot or a source.
-function isPreservedSource(rel) {
-  return preservationClass(rel) !== null;
-}
-
-// ── slug-form index (resolution with collision detection) ──────────────────────
-// Unlike lint's buildSlugMap (a Set that silently dedups collisions), rename
-// needs to KNOW when a form is shared, so it maps each form → the set of page
-// rels that expose it. precedence forms per page: full noExt slug, bare
-// basename, dir-relative (drop the leading scan-dir segment).
-const dirRelForm = (slug) => slugForms(slug).dirRel;
-
-function buildFormIndex(pages) {
-  const index = new Map(); // form → Set<rel>
-  const add = (form, rel) => {
-    if (!form) return;
-    if (!index.has(form)) index.set(form, new Set());
-    index.get(form).add(rel);
-  };
-  for (const p of pages) {
-    add(p.slug, p.rel);
-    // sources/* are full-slug-only link targets, exactly as lint's
-    // collectLinkTargets treats them: a bare `[[name]]` must NOT resolve to a
-    // source file. Adding their bare/dir-relative aliases here would make a real
-    // page's bare link look ambiguous and skip a legitimate rewrite.
-    if (/(^|\/)sources(\/|$)/.test(p.rel)) continue;
-    add(p.bare, p.rel);
-    add(dirRelForm(p.slug), p.rel);
-  }
-  return index;
-}
-
-// Classify a link target against the from-page. Returns the form KIND when the
-// target points at from-page, plus whether that form is ambiguous (shared with
-// another page → unsafe to auto-rewrite).
-function classifyTarget(target, fromPage, formIndex) {
-  const owners = formIndex.get(target);
-  if (!owners || !owners.has(fromPage.rel)) return { kind: null, ambiguous: false };
-  const ambiguous = owners.size > 1;
-  let kind = null;
-  if (target === fromPage.slug) kind = 'full';
-  else if (target === dirRelForm(fromPage.slug)) kind = 'dirrel';
-  else if (target === fromPage.bare) kind = 'bare';
-  return { kind, ambiguous };
-}
-
-// The new target string for a matched form kind — same kind, new page.
-function newTargetFor(kind, toPage) {
-  if (kind === 'full') return toPage.slug;
-  if (kind === 'dirrel') return dirRelForm(toPage.slug) ?? toPage.bare;
-  return toPage.bare; // bare
-}
-
-// ── wikilink masking (mirror lint.mjs stripNonWikilinkRegions) ──────────────────
-// Blank out fenced code, inline code, and HTML comments WITHOUT changing length,
-// so a [[ref]] match index in the mask aligns with the same index in the source.
-// Rewriting then edits the source at those exact spans, never touching a link
-// that only appears inside a code sample.
-function maskNonWikilinkRegions(content) {
-  let out = content;
-  out = out.replace(/^[ \t]{0,3}```[\s\S]*?^[ \t]{0,3}```/gm, (m) => m.replace(/[^\n]/g, ' '));
-  out = out.replace(/^[ \t]{0,3}~~~[\s\S]*?^[ \t]{0,3}~~~/gm, (m) => m.replace(/[^\n]/g, ' '));
-  out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
-  out = out.replace(/``[^`\n]*``/g, (m) => ' '.repeat(m.length));
-  out = out.replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
-  return out;
-}
-
-// Parse the inside of a `[[ ... ]]` into { target, suffix } where suffix is the
-// alias/anchor tail to preserve verbatim (including a table-escaped `\|`). The
-// target capture stops before an optional `\` preceding the `|`/`#` delimiter,
-// matching lint's extractor exactly.
-function splitLinkBody(body) {
-  const m = body.match(/^([^|#\\]+?)(\\?[|#][\s\S]*)?$/);
-  if (!m) return null;
-  return { target: m[1].trim(), suffix: m[2] || '' };
-}
+// ── preservation class of a link-source path, form index, masking, and link-body
+// parsing (preservationClass / isPreservedSource / dirRelForm / buildFormIndex /
+// classifyTarget / newTargetFor / maskNonWikilinkRegions / splitLinkBody) now
+// live in ./lib/slug-resolver.mjs, shared with lint.mjs's existence-check mode.
+// Directory mode's own notes on the two preservation classes: 'timerecord' is
+// skipped as a link SOURCE outside the moved subtree, but a time-record INSIDE
+// the moved subtree that links a moving sibling must update that intra-subtree
+// path label (the page genuinely moved); see runDirectory. 'sources' is never
+// rewritten even inside a moved subtree: a directory move must not claim
+// ownership over the bytes of an external source transcribed verbatim.
 
 // Rewrite every inbound reference to fromPage in `content`. Returns
 // { content, rewrites, ambiguous } where rewrites/ambiguous list the links
@@ -316,7 +235,9 @@ function guardExistingMarker(args, thisMarker) {
     );
   }
   const same =
-    marker.mode === thisMarker.mode && marker.from === thisMarker.from && marker.to === thisMarker.to;
+    marker.mode === thisMarker.mode &&
+    marker.from === thisMarker.from &&
+    marker.to === thisMarker.to;
   if (!same) {
     fail(
       args,
@@ -468,40 +389,10 @@ function rewriteContentDir(content, movedByRel, formIndex, aliasPreserve) {
   return { content: out, rewrites, ambiguous };
 }
 
-// Verify a path resolves — following any symlink ANCESTOR — to a location inside
-// the real vault root. A lexical ../-check cannot catch this: `projects/link/new`
-// where `projects/link` → /tmp/outside is lexically in-vault, yet renameSync would
-// follow the symlink and write across the vault boundary. The destination may not
-// exist, so the deepest existing prefix is resolved (its realpath is where a write
-// would actually land). Fail-closed: returns false on any resolution error.
-//
-// The walk uses lstat (NOT existsSync) so a DANGLING symlink prefix is detected as
-// present-but-unresolvable rather than skipped as absent — otherwise the walk would
-// step past it to an in-vault parent and wrongly report containment, letting an
-// external rewrite land before renameSync crashes on the dangling target.
-function realContainedInVault(absPath, realRoot) {
-  let probe = absPath;
-  // Walk up to the deepest path component that exists as a link-or-real entry.
-  for (;;) {
-    let exists = true;
-    try {
-      lstatSync(probe);
-    } catch {
-      exists = false;
-    }
-    if (exists) break;
-    const parent = dirname(probe);
-    if (parent === probe) return false;
-    probe = parent;
-  }
-  let real;
-  try {
-    real = realpathSync(probe); // follows links; throws on a dangling symlink
-  } catch {
-    return false;
-  }
-  return real === realRoot || real.startsWith(realRoot + sep);
-}
+// realContainedInVault now lives in ./lib/slug-resolver.mjs (imported above),
+// reused as-is: `projects/link/new` where `projects/link` → /tmp/outside is
+// lexically in-vault, yet renameSync would follow the symlink and write
+// across the vault boundary, which is exactly what it guards against below.
 
 // The destination's deepest existing ancestor must be a directory. Otherwise
 // mkdirSync(dirname, {recursive}) fails with ENOTDIR — but only AFTER the inbound
@@ -760,7 +651,10 @@ function runDirectory(args, fromDirRel, ignorePatterns) {
       // instead of an unsafe write-then-remove fallback; every write above is
       // already atomic, so a re-run picks up cleanly.
       if (err.code !== 'EXDEV') throw err;
-      fail(args, `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`);
+      fail(
+        args,
+        `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`,
+      );
     }
     clearRenameMarker(args);
     moved = true;
@@ -974,7 +868,10 @@ function run(args) {
         // removes. fromPage.path still holds the valid (possibly rewritten)
         // body, so a re-run picks up cleanly once the device issue is gone.
         if (err.code !== 'EXDEV') throw err;
-        fail(args, `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`);
+        fail(
+          args,
+          `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`,
+        );
       }
     }
     clearRenameMarker(args);

package/scripts/uninstall.mjs

@@ -14,6 +14,24 @@
  *   --force-commands     Remove user-modified slash commands instead of preserving them
  *   --force-extensions   Remove user-modified extension files (hypo-ext-*) instead of preserving them
  *   --hooks-dir=<path>   Override Claude hooks directory (default: ~/.claude/hooks)
+ *   --hypo-dir=<path>    Wiki vault to remove the pre-commit hook from (default: auto-resolve,
+ *                        same rules as init/lint/query)
+ *   --shell-config=<path> Shell rc file to strip the shell block from (default: checks both
+ *                        ~/.zshrc and ~/.bashrc, since init may have run under either shell)
+ *   --keep-shell         Skip the shell rc `claude()` block removal entirely
+ *   --keep-wiki-hook     Skip the wiki pre-commit hook removal entirely
+ *
+ * The wiki's git pre-commit hook and the shell rc's `claude()` wrapper function are removed
+ * only when they still carry the marker init.mjs wrote (WIKI_PRE_COMMIT_MARKER_START /
+ * SHELL_MARKER_START, both from ./lib/git-hooks-dir.mjs). A user's own pre-commit hook, a
+ * symlinked hook target, and any rc content outside the marker block are never touched.
+ *
+ * --hooks-dir only redirects where the ~/.claude/hooks/*.mjs removal looks; it does NOT bound
+ * the rc-block and wiki-hook removals above, since those live outside ~/.claude entirely and a
+ * hypo-dir override already exists for the latter. A caller that wants an uninstall run scoped
+ * to a throwaway hooks dir (a sandboxed CI check, for instance) and NOT touching the real
+ * machine's shell rc files or scanning for a real vault must say so explicitly with
+ * --keep-shell --keep-wiki-hook.
  *
  * Extensions: hypo-ext-* hard-copies under
  * ~/.claude/{hooks,commands,skills,agents}/ and ~/.codex/{hooks,commands}/ (with
@@ -23,7 +41,16 @@
  * does not follow them). The wiki source (~/hypomnema/extensions/) is preserved.
  */
 
-import { existsSync, readFileSync, writeFileSync, rmSync, rmdirSync, readdirSync } from 'fs';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  rmdirSync,
+  readdirSync,
+  statSync,
+  realpathSync,
+} from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
@@ -48,6 +75,20 @@ import {
   buildHookCommand,
 } from './lib/extensions.mjs';
 import { removeProvenanceSidecar } from './lib/pkg-provenance.mjs';
+import {
+  hooksDirForInstall,
+  unsafeHookTargetReason,
+  findMarkerSpan,
+  isOwnedWikiPreCommitBody,
+  isOwnedShellFunctionBody,
+  canonicalize,
+  isInside,
+  WIKI_PRE_COMMIT_MARKER_START,
+  WIKI_PRE_COMMIT_MARKER_END,
+  SHELL_MARKER_START,
+  SHELL_MARKER_END,
+} from './lib/git-hooks-dir.mjs';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -428,6 +469,226 @@ function stripExtensionSettings(settingsPath, hooksDir, apply, ownedCommands = n
   return { stripped };
 }
 
+// ── wiki pre-commit hook removal ────────────────────────────────────────────
+
+// Mirrors init.mjs's own resolution (hooksDirForInstall) as the PRIMARY
+// candidate, so this finds the hook wherever init would put it today,
+// including under a core.hooksPath override. A second, best-effort candidate
+// (the vault's plain .git/hooks/pre-commit) is checked too, but it only
+// recovers ONE specific drift: an install that went to the default .git/hooks
+// and had core.hooksPath pointed elsewhere afterward. It does not recover the
+// general case (an install that went to a non-default core.hooksPath which was
+// then repointed somewhere else again), since the only fallback candidate is
+// the plain .git/hooks path, never the original custom one. Both candidates go
+// through the same marker/ownership gate below, so widening the search costs
+// nothing in safety, only in how many places we bother to look.
+// A hook that still carries our marker is removed; a user's own pre-commit (no
+// marker), a symlinked/non-regular target, and a hook whose marker is
+// duplicated, swapped, or missing its shebang are all left standing.
+// `pre-commit.bak` (init's --force-commands backup of the user's original
+// hook) is never removed here, only reported so the user knows it exists.
+function removeWikiPreCommitHook(hypoDir, apply) {
+  const result = { removed: [], skipped: [], bakPresent: [] };
+
+  if (!hypoDir || !existsSync(join(hypoDir, 'hypo-config.md'))) {
+    result.skipped.push(
+      `no Hypomnema vault found${hypoDir ? ` at ${hypoDir}` : ''} — nothing to remove`,
+    );
+    return result;
+  }
+
+  const candidateDirs = [];
+  const { dir: hooksDir, skip } = hooksDirForInstall(hypoDir);
+  if (hooksDir) candidateDirs.push(hooksDir);
+  else if (skip) result.skipped.push(skip);
+
+  // Best-effort fallback: only when `.git` is a real directory here (a plain
+  // checkout, not a linked worktree's gitdir-pointer FILE, which this join
+  // would misread entirely — resolveGitHooksDir already handles that layout
+  // correctly via the primary candidate above).
+  const legacyGitDir = join(hypoDir, '.git');
+  if (existsSync(legacyGitDir) && statSync(legacyGitDir).isDirectory()) {
+    const legacyHooksDir = join(legacyGitDir, 'hooks');
+    // Canonicalize before trusting this candidate. The primary path above
+    // already refuses to write through a `.git/hooks` that resolves outside
+    // the repo (resolveGitHooksDir's `owned` check), but that refusal does
+    // nothing for THIS fallback, which built its candidate by string join,
+    // not by resolving anything. If `.git/hooks` (or any ancestor of it) is
+    // itself a symlink to an external directory, the join above still points
+    // there, and the leaf-only unsafeHookTargetReason() below cannot see it:
+    // lstat on the FINAL path component says nothing about a symlink the OS
+    // already followed to reach that component. Codex reproduced exactly
+    // this (2026-08-27): a symlinked `.git/hooks` pointing at an external
+    // directory let this fallback delete a file the primary path had
+    // already, correctly, refused to touch.
+    const resolvedCandidate = canonicalize(legacyHooksDir);
+    if (isInside(resolvedCandidate, canonicalize(legacyGitDir))) {
+      candidateDirs.push(legacyHooksDir);
+    }
+  }
+
+  const seen = new Set();
+  for (const dir of candidateDirs) {
+    const hookPath = join(dir, 'pre-commit');
+    // Dedupe by the resolved real path, not the string: the primary candidate
+    // is realpath'd internally (resolveGitHooksDir's canonicalize) while the
+    // legacy join above is not, so the same physical file can arrive under two
+    // different-looking paths. Falling back to the raw path when the file does
+    // not exist is fine — two distinct absent candidates never collide.
+    let key = hookPath;
+    try {
+      key = realpathSync(hookPath);
+    } catch {
+      // leave key as hookPath
+    }
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const unsafe = unsafeHookTargetReason(hookPath);
+    if (unsafe) {
+      result.skipped.push(`${hookPath} (${unsafe})`);
+      continue;
+    }
+    if (!existsSync(hookPath)) continue; // already absent, nothing to report
+
+    let content;
+    try {
+      content = readFileSync(hookPath, 'utf-8');
+    } catch (e) {
+      result.skipped.push(`${hookPath} (cannot read: ${e.code || e.message})`);
+      continue;
+    }
+    if (
+      !content.includes(WIKI_PRE_COMMIT_MARKER_START) ||
+      !content.includes(WIKI_PRE_COMMIT_MARKER_END)
+    ) {
+      result.skipped.push(`${hookPath} (not managed by Hypomnema — preserving)`);
+      continue;
+    }
+
+    // Report the backup only past the ownership gate above: a vault with no
+    // Hypomnema hook at all (or a symlinked/unreadable one) can still happen
+    // to have a stray pre-commit.bak lying around, and attributing that to
+    // "from --force-commands" before confirming this IS a Hypomnema-managed
+    // hook would misdescribe someone else's file.
+    const bakPath = `${hookPath}.bak`;
+    if (existsSync(bakPath)) result.bakPresent.push(bakPath);
+
+    const span = findMarkerSpan(content, WIKI_PRE_COMMIT_MARKER_START, WIKI_PRE_COMMIT_MARKER_END);
+    if (!span.ok) {
+      result.skipped.push(`${hookPath} (${span.reason} — preserving)`);
+      continue;
+    }
+
+    // init writes the marker as the ENTIRE hook body: a bare "#!/bin/sh\n"
+    // right before WIKI_PRE_COMMIT_MARKER_START, nothing after
+    // WIKI_PRE_COMMIT_MARKER_END. A file with no shebang there was never
+    // written by init even if it happens to carry a well-formed marker span
+    // (hand-authored or copy-pasted) — deleting it on marker presence alone
+    // would remove code we do not own. A user who appended their own check
+    // after the block turned this into a file we only partly own. init's own
+    // --force-commands path handles the analogous case by OVERWRITING with
+    // equivalent content (a safe merge); uninstall has no such repair, only
+    // rmSync, so treating "extra content" the same as "fully ours" would
+    // silently delete the user's check with no way back.
+    const before = content.slice(0, span.startIdx);
+    const after = content.slice(span.endIdx + WIKI_PRE_COMMIT_MARKER_END.length);
+    if (!/^#![^\n]*\n$/.test(before)) {
+      result.skipped.push(
+        `${hookPath} (hook carries content before the Hypomnema block — preserving)`,
+      );
+      continue;
+    }
+    if (after.trim() !== '') {
+      result.skipped.push(
+        `${hookPath} (hook carries content after the Hypomnema block — preserving)`,
+      );
+      continue;
+    }
+
+    // A well-formed span (one start, one end, in order) with a bare shebang
+    // before it and nothing after proves only the SHAPE around the block is
+    // ours. It says nothing about what is INSIDE the block — a marker pair
+    // can be hand-copied around arbitrary content, including a user's own
+    // check (codex BLOCKER, 2026-08-27). Refuse unless the body itself is
+    // recognizable as what wikiPreCommitContent() writes.
+    if (!isOwnedWikiPreCommitBody(content, span)) {
+      result.skipped.push(
+        `${hookPath} (marker span present but its body does not match the hook Hypomnema writes — preserving)`,
+      );
+      continue;
+    }
+
+    if (apply) rmSync(hookPath);
+    result.removed.push(hookPath);
+  }
+
+  // Every candidate came back plain-absent (existsSync(hookPath) was false for
+  // all of them): nothing was removed, and nothing was skipped-with-a-reason
+  // either, so silence here would read as "there was nothing to say" when it
+  // actually means "the fallback above did not find a marked hook anywhere it
+  // looked". Report that explicitly instead of just going quiet — and name the
+  // one drift this cannot recover from: if core.hooksPath pointed somewhere
+  // else at install time and has since been repointed AGAIN (custom to
+  // custom, not the default-to-custom case the fallback above does cover),
+  // the hook Hypomnema wrote is still sitting at that first custom path,
+  // still executable, and can fail a future commit there with no cleanup
+  // path from this run.
+  if (candidateDirs.length > 0 && result.removed.length === 0 && result.skipped.length === 0) {
+    result.skipped.push(
+      `no Hypomnema-marked pre-commit hook found in ${candidateDirs.join(' or ')} — if core.hooksPath ` +
+        `pointed somewhere else at install time and has since changed again, the hook Hypomnema wrote ` +
+        `may still be sitting at that earlier path; it will keep running on every commit there and can ` +
+        `fail commits until it is removed by hand`,
+    );
+  }
+
+  return result;
+}
+
+// ── shell function block removal ────────────────────────────────────────────
+
+// init picks ONE rc file at install time from $SHELL (or --shell-config), but
+// $SHELL by uninstall time may point somewhere else, or init may have run in
+// a different shell session altogether — so both common rc files are checked
+// by default rather than guessing one. Only the marker span itself is
+// stripped; every other byte in the file, including surrounding blank lines,
+// is left exactly as it was. A malformed span (duplicated or swapped markers,
+// see findMarkerSpan above) leaves the file completely untouched: an rc file
+// is the user's own, and this script has no backup to restore it from.
+function removeShellFunctionBlock(shellConfigPath, apply) {
+  if (!existsSync(shellConfigPath)) return null;
+  const content = readFileSync(shellConfigPath, 'utf-8');
+  if (!content.includes(SHELL_MARKER_START) && !content.includes(SHELL_MARKER_END)) {
+    return null; // block not present here at all
+  }
+
+  const span = findMarkerSpan(content, SHELL_MARKER_START, SHELL_MARKER_END);
+  if (!span.ok) {
+    return { path: shellConfigPath, removed: false, skipped: span.reason };
+  }
+
+  // A well-formed span proves only that a start and an end marker exist in
+  // order — nothing about what sits between them. A marker pair copy-pasted
+  // around a user's own function (or appended to, inside the same span) would
+  // pass every check above and get removed along with that user's code
+  // (codex BLOCKER, 2026-08-27). Refuse unless the body between the markers
+  // is byte-identical to what init.mjs installs.
+  if (!isOwnedShellFunctionBody(content, span)) {
+    return {
+      path: shellConfigPath,
+      removed: false,
+      skipped:
+        'marker span present but its body does not match the shell function Hypomnema installs',
+    };
+  }
+
+  const updated =
+    content.slice(0, span.startIdx) + content.slice(span.endIdx + SHELL_MARKER_END.length);
+  if (apply) writeFileSync(shellConfigPath, updated);
+  return { path: shellConfigPath, removed: true, skipped: null };
+}
+
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -437,13 +698,29 @@ function parseArgs(argv) {
     hooksDir: null,
     forceCommands: false,
     forceExtensions: false,
+    hypoDir: null,
+    shellConfig: null,
+    keepShell: false,
+    keepWikiHook: false,
   };
   for (const arg of argv.slice(2)) {
     if (arg === '--apply') args.apply = true;
     else if (arg === '--codex') args.codex = true;
     else if (arg === '--force-commands') args.forceCommands = true;
     else if (arg === '--force-extensions') args.forceExtensions = true;
+    else if (arg === '--keep-shell') args.keepShell = true;
+    else if (arg === '--keep-wiki-hook') args.keepWikiHook = true;
     else if (arg.startsWith('--hooks-dir=')) args.hooksDir = arg.slice(12);
+    // expandHome mirrors init.mjs's own --hypo-dir/--shell-config parsing
+    // (init.mjs's parseArgs) exactly, reusing the same function from
+    // ./lib/hypo-root.mjs rather than re-deriving it. Uninstall must undo
+    // whatever path init actually wrote to disk, and init resolves a leading
+    // "~/" itself (the shell never does, since the value arrives already
+    // quoted inside "--flag=value"); skipping that step here would silently
+    // fail to find the vault or rc file a user installed with "~/..." to
+    // begin with.
+    else if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--shell-config=')) args.shellConfig = expandHome(arg.slice(15));
   }
   return args;
 }
@@ -580,6 +857,22 @@ function stripSettingsJson(settingsPath, hooksDir, hookMap, apply) {
 const args = parseArgs(process.argv);
 const dryRun = !args.apply;
 
+// --hooks-dir only redirects the ~/.claude/hooks/*.mjs cleanup below (see the
+// module doc comment). A caller who passes it alone, expecting the run to
+// stay confined to that throwaway directory, is surprised when the real
+// machine's shell rc files and auto-resolved wiki vault get touched too
+// (codex CONCERN, 2026-08-27). Warn before any of the removal functions run,
+// not just in the final report, since by the time that report prints under
+// --apply the files are already gone.
+if (args.hooksDir && !args.keepShell && !args.keepWikiHook) {
+  console.error(
+    `⚠ --hooks-dir only redirects the ~/.claude/hooks/*.mjs cleanup. This run will still ` +
+      `${dryRun ? 'inspect' : 'modify'} the real shell rc files (~/.zshrc, ~/.bashrc, or --shell-config) ` +
+      `and the auto-resolved wiki vault's pre-commit hook. Pass --keep-shell and/or --keep-wiki-hook to ` +
+      `scope this run to --hooks-dir only.`,
+  );
+}
+
 const { hookMap, hookFiles } = loadHookFiles();
 
 const claudeHooksDir = args.hooksDir ?? join(HOME, '.claude', 'hooks');
@@ -589,6 +882,39 @@ const hookResult = removeHookFiles(claudeHooksDir, hookFiles, args.apply);
 const settingsResult = stripSettingsJson(claudeSettings, claudeHooksDir, hookMap, args.apply);
 const commandResult = removeCommands(args.apply, args.forceCommands);
 
+// Wiki-side cleanup: the git pre-commit hook and the shell rc block init.mjs
+// installs outside ~/.claude entirely. Both are independent of --codex/--hooks-dir:
+// --hooks-dir only redirects the ~/.claude/hooks/*.mjs removal above, it does not
+// bound these two, since they live outside ~/.claude and already have their own
+// scoping flags (--hypo-dir, --shell-config). A caller that wants an uninstall run
+// confined to a throwaway --hooks-dir and NOT touching the real machine's shell rc
+// files or scanning for a real vault (a sandboxed CI check, for instance) says so
+// explicitly with --keep-shell / --keep-wiki-hook rather than relying on
+// --hooks-dir to imply it.
+// resolveHypoRoot() scans a fixed list of candidate directories under HOME
+// (see ./lib/hypo-root.mjs). --keep-wiki-hook says the caller does not want
+// this run touching a vault at all, so the scan itself is skipped rather than
+// run and then discarded — matching the module doc comment above ("--keep-
+// wiki-hook" is described as skipping the cleanup outright, not as skipping
+// only the removal after still resolving a root).
+const hypoDir = args.keepWikiHook ? null : (args.hypoDir ?? resolveHypoRoot());
+const preCommitResult = args.keepWikiHook
+  ? {
+      removed: [],
+      skipped: ['--keep-wiki-hook passed: wiki pre-commit hook cleanup skipped'],
+      bakPresent: [],
+    }
+  : removeWikiPreCommitHook(hypoDir, args.apply);
+
+const shellConfigCandidates = args.shellConfig
+  ? [args.shellConfig]
+  : [join(HOME, '.zshrc'), join(HOME, '.bashrc')];
+const shellBlockOutcomes = args.keepShell
+  ? []
+  : shellConfigCandidates.map((p) => removeShellFunctionBlock(p, args.apply)).filter(Boolean);
+const shellBlockResults = shellBlockOutcomes.filter((r) => r.removed).map((r) => r.path);
+const shellBlockSkipped = shellBlockOutcomes.filter((r) => !r.removed);
+
 // 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
@@ -736,6 +1062,27 @@ if (hookResult.missing.length)
   lines.push(
     `⊘ Already absent (${hookResult.missing.length}):\n${hookResult.missing.map((p) => `  ${p}`).join('\n')}`,
   );
+if (preCommitResult.removed.length)
+  lines.push(
+    `✓ Wiki pre-commit hook ${dryRun ? 'to remove' : 'removed'} (${preCommitResult.removed.length}):\n${preCommitResult.removed.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (preCommitResult.skipped.length)
+  lines.push(
+    `⊘ Wiki pre-commit hook preserved:\n${preCommitResult.skipped.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (preCommitResult.bakPresent.length)
+  lines.push(
+    `ⓘ Pre-commit backup left in place (from --force-commands, never touched by uninstall):\n${preCommitResult.bakPresent.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (shellBlockResults.length)
+  lines.push(
+    `✓ Shell function block ${dryRun ? 'to remove' : 'removed'} (${shellBlockResults.length}):\n${shellBlockResults.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (shellBlockSkipped.length)
+  lines.push(
+    `⊘ Shell function block preserved:\n${shellBlockSkipped.map((r) => `  ${r.path} (${r.skipped})`).join('\n')}`,
+  );
+
 if (settingsResult.error) lines.push(`⚠ ${settingsResult.error}`);
 if (claudeExtSettings.error) lines.push(`⚠ ${claudeExtSettings.error}`);
 if (codexExtSettings.error) lines.push(`⚠ ${codexExtSettings.error}`);
@@ -750,7 +1097,9 @@ if (
   !pkgJsonRemoved &&
   !commandResult.skippedUserModified.length &&
   !extSkippedUserModified.length &&
-  !extSkippedNonRegular.length
+  !extSkippedNonRegular.length &&
+  !preCommitResult.removed.length &&
+  !shellBlockResults.length
 ) {
   lines.push('Nothing to uninstall — Hypomnema does not appear to be installed.');
 }

package/skills/crystallize/SKILL.md

@@ -50,8 +50,8 @@ If `/hypo:crystallize` was invoked as a session-close action, run through this c
 Surface each of these four to the user first. Every one is **advisory** (identity guard): the user confirms or declines, and none performs an automatic action, writes a file on its own, or bypasses the mandatory gate.
 
 - **Trivial-session check (#44)** — Was this session trivial (a single bug fix, a single-file edit, or Q&A with no durable artifact)? If so, recommend skipping session-close: *"이 세션은 trivial해 보입니다 — session-close를 건너뛸까요?"* A trivial skip is a recommendation, **not** a bypass: it must not mark the session closed, must not run `--mark-session-closed`, and must not claim `/compact` can pass. Any real close still requires all 5 mandatory files.
-- **ADR-candidate check (#41)** — Did this session make an architectural or design decision (a new pattern, a tradeoff, a convention)? If yes, ask whether it warrants an ADR and capture that intent in the session-log entry. If nothing rose to ADR level, you may record the literal marker `ADR 없음 — <one-line reason>` in that same session-log entry — but gate it on #42's bar, not this one: the marker is machine-read and W8 treats a session-log entry carrying `ADR 없음` (and no ADR reference) as a *no-design* session, excluding it from the design-history staleness check. So write `ADR 없음` only when the session had no design change at all. If it had a sub-ADR design shift (background / tradeoff / differentiation), append to design-history (#42a) instead — writing the marker there would suppress the W8 nudge that shift needs. **Never auto-write an ADR file** — the session-log note is the only action here.
-- **design-history staleness check (#42)** — Two branches, so a stale W8 never blocks a clean close: (a) if this session changed design decisions that `projects/<name>/design-history.md` does not yet reflect — including background / tradeoff / differentiation shifts that are below ADR level but still belong in the ledger — recommend appending to it now (W8 flags this mechanically; an active-project W8 hard-blocks at PreCompact — append before you commit, not after the gate fires). (b) only if this session made **no** design change at all does the `ADR 없음` marker from #41 exempt the entry from W8 — do **not** touch design-history. Caution: `ADR 없음` means "no design change," which is a stricter bar than "no ADR-level decision." A session with a sub-ADR design shift should take branch (a) and append; writing `ADR 없음` there would suppress the W8 nudge it actually needs. If the file does not exist, skip silently — do **not** create it just for this check. Never auto-update it.
+- **ADR-candidate check (#41).** Did this session make an architectural or design decision (a new pattern, a tradeoff, a convention)? If yes, ask whether it warrants an ADR and capture that intent in the session-log entry. If nothing rose to ADR level, you may record the literal marker `ADR 없음: <one-line reason>` in that same session-log entry, but gate it on #42's bar, not this one: the marker is machine-read and W8 treats a session-log entry carrying `ADR 없음` (and no ADR reference) as a *no-design* session, excluding it from the design-history staleness check. So write `ADR 없음` only when the session had no design change at all. If it had a sub-ADR design shift (background, tradeoff, or differentiation), append to design-history (#42a) instead: writing the marker there would suppress the W8 nudge that shift needs. **Never auto-write an ADR file.** The session-log note is the only action here. This check carries no `decisions/` directory precondition: run it whether or not that directory exists.
+- **design-history staleness check (#42).** Two branches, so a stale W8 never blocks a clean close: (a) if this session changed design decisions that `projects/<name>/design-history.md` does not yet reflect (including background, tradeoff, or differentiation shifts that are below ADR level but still belong in the ledger), recommend appending to it now: W8 flags this mechanically, and an active-project W8 hard-blocks at PreCompact, so append before you commit, not after the gate fires. **If the file does not exist yet and this session had a design change, recommend creating it now** with that change as the first entry; lint separately flags a missing-but-needed file as W14, a warning that never blocks. (b) only if this session made **no** design change at all does the `ADR 없음` marker from #41 exempt the entry from W8; do **not** touch design-history, and do not create the file just to satisfy this branch's check. Caution: `ADR 없음` means "no design change," which is a stricter bar than "no ADR-level decision." A session with a sub-ADR design shift should take branch (a) and append; writing `ADR 없음` there would suppress the W8 nudge it actually needs. Never auto-write the file yourself in either branch: recommend it, and let the user decide.
 - **Ingest check (#43)** — Did this session consume trustworthy external knowledge (a fetched URL, official docs, or code you verified directly)? If so, recommend running `/hypo:ingest` to capture it under `sources/`. Proceed only on the user's confirmation.
 
 When uncertain, surface the question rather than skip it. None of the four blocks the close or writes on its own.