hypomnema 1.8.2 → 1.8.4

package/scripts/lib/hook-inventory.mjs

@@ -0,0 +1,150 @@
+// hook-inventory.mjs — the one grammar every hooks.json/shared.json consumer reads
+// through: smoke-plugin.mjs, init.mjs, upgrade.mjs, doctor.mjs, uninstall.mjs.
+//
+// Before this file existed, five scripts each grew their own regex for pulling a
+// .mjs basename out of a hooks.json `command` string, and the five disagreed:
+//   - smoke-plugin accepted ANY path after `${CLAUDE_PLUGIN_ROOT}/`, so a command
+//     pointing at `${CLAUDE_PLUGIN_ROOT}/scripts/foo.mjs` (the wrong directory —
+//     init only ever copies hooks/) passed smoke as long as that file happened to
+//     exist, while init/upgrade/doctor/uninstall all resolve the same command to
+//     `hooks/foo.mjs` and never look in scripts/ at all.
+//   - init/upgrade/doctor took the LAST `.mjs` path segment in the command, so a
+//     trailing argument like `--config bar.mjs` would have picked `bar.mjs` up as
+//     the hook file instead of the hook itself.
+//   - uninstall anchored on `/hooks/([^/\s]+\.mjs)$` — the command had to literally
+//     END in `.mjs`, so the same trailing-argument shape it would silently ignore
+//     instead of misreading.
+// One parser closes all three gaps by only ever accepting one shape.
+//
+// This module also folds in the existence check that used to be missing entirely:
+// loadHookInventory() only returns ok:true once every name on both lists resolves
+// to a real regular file under `<pkgRoot>/hooks/`. A caller that runs this BEFORE
+// its first write (as init.mjs now does) can never install a partial hook set from
+// a package a file was dropped out of.
+//
+// Deliberately does NOT accept the legacy bare-filename group format
+// (`"hooks.json"`: `{ "SomeEvent": ["foo.mjs"] }`) that ../core-hooks.mjs's
+// readCoreHooksConfig still tolerates for reverse-capture's basename reservation.
+// That tolerance exists so a stale or hand-edited hooks.json never lets a core
+// hook slip into a user's captured extensions; it has nothing to do with what
+// install/uninstall are willing to act on, so narrowing the grammar here does not
+// need to touch core-hooks.mjs at all.
+
+import { join } from 'node:path';
+import { readCoreHooksConfig } from './core-hooks.mjs';
+import { isRegularFile } from './pkg-json.mjs';
+
+// A plain .mjs basename: word characters, dots, and hyphens only, no path
+// separator (so a joined path can never climb out of the directory it is joined
+// onto) and no leading dot (rules out a hidden file and `..`, which does not
+// match `\w` but a bare `.` prefix like `.mjs` alone still would). Mirrors the
+// basename check smoke-plugin.mjs already applied to hooks/shared.json entries.
+const SAFE_MJS_BASENAME = /^[\w.-]+\.mjs$/;
+
+export function isSafeMjsBasename(name) {
+  return typeof name === 'string' && SAFE_MJS_BASENAME.test(name) && !name.startsWith('.');
+}
+
+// The one command shape this module accepts: `${CLAUDE_PLUGIN_ROOT}/hooks/<basename>.mjs`,
+// optionally followed by more of the command (a trailing argument, a redirect —
+// anything after whitespace or a closing quote). No sub-directory under hooks/,
+// no other top-level directory, no bare filename with no `${CLAUDE_PLUGIN_ROOT}/hooks/`
+// prefix at all.
+const PLUGIN_HOOKS_TARGET = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/([^\s/"'`]+)(?=$|[\s"'`])/;
+
+/**
+ * Extract the hooks/<basename>.mjs a command string targets, or null when the
+ * command does not match the one accepted shape (wrong directory, a
+ * sub-directory, a basename that fails isSafeMjsBasename, or no
+ * `${CLAUDE_PLUGIN_ROOT}/hooks/` segment at all).
+ */
+export function extractPluginHookBasename(command) {
+  if (typeof command !== 'string') return null;
+  const m = command.match(PLUGIN_HOOKS_TARGET);
+  if (!m) return null;
+  return isSafeMjsBasename(m[1]) ? m[1] : null;
+}
+
+/**
+ * Load, narrowly validate, and existence-check the hook inventory rooted at
+ * `pkgRoot`: hooks/hooks.json's per-event basenames plus hooks/shared.json's
+ * shared-module basenames. Fails closed on the FIRST problem, whether that is a
+ * read/parse failure (delegated to readCoreHooksConfig), an empty hooks map, a
+ * command that does not match the one accepted grammar, an unsafe shared.json
+ * basename, or a named file that is not actually a regular file under
+ * `<pkgRoot>/hooks/`.
+ *
+ * @param {string} pkgRoot
+ * @returns {{ ok: true, hookMap: Record<string, string[]>, shared: string[] }
+ *   | { ok: false, error: string }}
+ */
+export function loadHookInventory(pkgRoot) {
+  const res = readCoreHooksConfig(pkgRoot);
+  if (!res.ok) return { ok: false, error: res.error };
+  const cfg = res.cfg;
+
+  if (Object.keys(cfg.hooks).length === 0) {
+    return { ok: false, error: 'hooks/hooks.json "hooks" must not be empty' };
+  }
+
+  const hookMap = {};
+  for (const [event, groups] of Object.entries(cfg.hooks)) {
+    const basenames = [];
+    for (const group of groups) {
+      // readCoreHooksConfig still accepts a bare-filename group (the legacy
+      // shape reverse-capture's basename reservation tolerates on purpose — see
+      // the module header). Every real install/uninstall consumer of THIS
+      // function only ever shipped the hook-group object form, so a bare string
+      // reaching here is not something any of the five knows how to act on.
+      if (typeof group === 'string') {
+        return {
+          ok: false,
+          error: `hooks.${event}: a bare filename group ("${group}") is not accepted here — wrap it in a hook-group object with an explicit command`,
+        };
+      }
+      if (!Array.isArray(group.hooks) || group.hooks.length === 0) {
+        return {
+          ok: false,
+          error: `hooks.${event}: a hook group must have a non-empty "hooks" array`,
+        };
+      }
+      for (const hook of group.hooks) {
+        if (hook.type !== 'command') {
+          return { ok: false, error: `hooks.${event}: hook entry "type" must be "command"` };
+        }
+        const base = extractPluginHookBasename(hook.command);
+        if (!base) {
+          return {
+            ok: false,
+            error: `hooks.${event}: command does not match "\${CLAUDE_PLUGIN_ROOT}/hooks/<basename>.mjs": ${hook.command}`,
+          };
+        }
+        basenames.push(base);
+      }
+    }
+    if (basenames.length === 0) {
+      return { ok: false, error: `hooks.${event} yields no hook files` };
+    }
+    hookMap[event] = basenames;
+  }
+
+  for (const file of cfg.shared) {
+    if (!isSafeMjsBasename(file)) {
+      return { ok: false, error: `hooks/shared.json: "${file}" is not a plain .mjs basename` };
+    }
+  }
+
+  // Existence, checked last and over the UNION of both lists: a caller that
+  // reaches this point has already paid for the grammar checks above, and a
+  // missing file (dropped from `package.json`'s `files` allowlist, or from a
+  // corrupted copy) is exactly the gap major C closed — nothing may be
+  // installed, refreshed, or reported healthy on the strength of a name alone.
+  const allBasenames = new Set([...Object.values(hookMap).flat(), ...cfg.shared]);
+  for (const base of allBasenames) {
+    if (!isRegularFile(join(pkgRoot, 'hooks', base))) {
+      return { ok: false, error: `hooks/${base} is not a file` };
+    }
+  }
+
+  return { ok: true, hookMap, shared: cfg.shared };
+}

package/scripts/lib/pkg-provenance.mjs

@@ -106,6 +106,14 @@ export function provenancePath(hooksDir) {
  * it is a doctor-only freshness signal, not part of the runtime contract
  * (hooks/hypo-shared.mjs never reads this field), so a sidecar the runtime
  * can verify should not be withheld just because the digest step failed.
+ *
+ * `managedFiles` (major D) is the same best-effort shape: the sorted basename
+ * list this run's own copy targeted (every hooks.json event command plus every
+ * hooks/shared.json entry, derived from `pkgRoot` the same way the digest
+ * above is). scripts/uninstall.mjs reads it back as a fallback source of truth
+ * when THIS package's own hooks.json can no longer be read at uninstall time —
+ * the sidecar was written by whatever package last actually ran the copy, so it
+ * names the truth of what is on disk even after the current package rots.
  */
 export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDir, dryRun) {
   let hypoSharedSha256;
@@ -115,12 +123,15 @@ export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDi
     return null;
   }
   const hooksDigest = computeHooksDigest(pkgRoot, hooksSrcDir);
+  const cfgRes = readCoreHooksConfig(pkgRoot);
+  const managedFiles = cfgRes.ok ? [...deriveCoreHookBasenames(cfgRes.cfg)].sort() : null;
   const dest = provenancePath(hooksDir);
   const data = {
     pkgRoot,
     pkgVersion,
     hypoSharedSha256,
     ...(hooksDigest ? { [HOOKS_DIGEST_FIELD]: hooksDigest } : {}),
+    ...(managedFiles ? { managedFiles } : {}),
     copiedAt: new Date().toISOString(),
   };
   if (!dryRun) atomicWriteJson(dest, data);

package/scripts/lib/plugin-detect.mjs

@@ -98,14 +98,20 @@ function readPkgVersionAt(root) {
   }
 }
 
-// A pkgRoot is "usable" as a DURABLE install root only if it is an ABSOLUTE path to
-// a real package directory whose package.json carries a version. A relative path
-// (e.g. installPath ".") would be resolved against the caller's cwd and break the
-// vault git hook from any other directory; a version-less package.json cannot be
-// attributed a version without lying. A bare path that merely exists is a pointer
-// the runtime cannot resolve scripts through. Shared by init's registry resolution,
-// its durable-root fallback, and upgrade's dualSkip provenance correction so they
-// all agree on what is real.
+// A pkgRoot is "usable" only if it is an ABSOLUTE path to a real package directory
+// whose package.json carries a version. A relative path (e.g. installPath ".")
+// would be resolved against the caller's cwd and break the vault git hook from any
+// other directory; a version-less package.json cannot be attributed a version
+// without lying. This is the WEAK predicate: it says nothing about WHOSE package
+// sits at that path, only that a version can be read from it. That is enough for a
+// diagnostic that reads and reports (doctor.mjs's per-row leaf-drift scan, which
+// deliberately widens rather than narrows — see leafVersionDrift above), but it is
+// NOT enough for a caller that adopts the path as Hypomnema's own durable identity
+// and writes it to a sidecar (hypo-pkg.json) or a vault's pre-commit hook: nothing
+// here stops a foreign package at an absolute, version-bearing path from being
+// adopted as if it were this one. isHypomnemaInstallRoot below is the strong
+// predicate for that case; keep the two in sync; a change to one's shape
+// (absolute + version) almost certainly belongs in the other too.
 export function usablePkgRoot(pkgRoot) {
   return (
     typeof pkgRoot === 'string' &&
@@ -116,6 +122,26 @@ export function usablePkgRoot(pkgRoot) {
   );
 }
 
+// The STRONG predicate: usablePkgRoot, AND the package at that path is literally
+// named "hypomnema". A registry or hypo-pkg.json entry can carry any absolute,
+// version-bearing path — a corrupted sidecar, a hand-edited registry row, or (per
+// the commit-time resolver's own `usable()` in git-hooks-dir.mjs) an attacker's
+// project — so a caller that RECORDS a root as durable identity (init.mjs's
+// resolveDurableRoot, selectEntry below) or WRITES it back to disk (upgrade.mjs's
+// dualSkip provenance correction) must check producer identity, not just
+// "a version is readable here". A caller that only READS for display (doctor.mjs's
+// per-row leaf scan) stays on the weak usablePkgRoot: narrowing it would silence a
+// foreign registry row doctor exists to surface, per the "does NOT exclude"
+// rationale on leafVersionDrift above.
+export function isHypomnemaInstallRoot(pkgRoot) {
+  if (!usablePkgRoot(pkgRoot)) return false;
+  try {
+    return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).name === 'hypomnema';
+  } catch {
+    return false;
+  }
+}
+
 // The version-shaped leaf of a plugin cache path (its last path component), or
 // null when that leaf does not look like a version. Claude Code names a plugin
 // cache directory after the release it copied in (`cache/<marketplace>/<name>/
@@ -185,10 +211,18 @@ export function leafVersionDrift(pkgRoot) {
 // #269 reimplemented this exact filter-then-prefer-scope rule at its call site,
 // in the opposite order, which silently swaps rows whenever the user row has no
 // gitCommitSha).
+// isHypomnemaInstallRoot, not the weak usablePkgRoot: this is the row
+// resolveEnabledPluginEntry hands to callers that RECORD it as durable identity
+// (init.mjs's resolveDurableRoot, upgrade.mjs's dualSkip provenance write), so a
+// registry row whose installPath merely resolves a readable version, without
+// being a real Hypomnema package, must not be selected here. codex reproduction
+// (2026-09-11): a registry row's package.json carried no `name` field at all and
+// was still adopted as the durable root under the old, name-blind check.
 function selectEntry(entries, scope) {
   return (
     entries.find(
-      (e) => e && (scope === undefined || e.scope === scope) && usablePkgRoot(e.installPath),
+      (e) =>
+        e && (scope === undefined || e.scope === scope) && isHypomnemaInstallRoot(e.installPath),
     ) ?? null
   );
 }

package/scripts/lib/template-schema-version.mjs

@@ -19,3 +19,50 @@ export function templateSchemaVersion(pkgRoot) {
     return null;
   }
 }
+
+// One line per SCHEMA.md version bump, naming what that version added over the
+// one before it. This is upgrade.mjs's only source for "what changed" text
+// when it tells a user their installed SCHEMA.md is behind — without it, the
+// notice can only name the two version numbers, and the two SCHEMA.md copies
+// diverge (translation, local additions) far enough that a raw diff is
+// dominated by noise unrelated to the actual upstream change. Add an entry
+// here whenever templates/SCHEMA.md's `version:` frontmatter bumps; a version
+// missing from this map falls back to the plain "review manually" notice
+// (schemaVersionDeltas below returns nothing for it), so leaving one out is
+// silent, not wrong.
+// Quote any key with a trailing zero. An unquoted `2.10:` is a NUMBER literal
+// and JS normalizes it to the string "2.1", so it would silently overwrite
+// 2.1's line (or hand 2.10's text to somebody upgrading across 2.1). Verified:
+// `Object.keys({2.10: 'x'})` is `['2.1']`. Prettier will not undo the quotes
+// there — stripping them would change meaning, so it leaves "2.10" alone even
+// though it rewrites '2.2' to 2.2. What prettier cannot save you from is
+// writing 2.10 unquoted in the first place, which is why a test reads this
+// file's text and rejects that shape rather than trusting the convention.
+export const SCHEMA_VERSION_DELTAS = {
+  2.2: 'documents `sources_consulted` on `type: synthesis` pages (lint W15/W16 read it to flag a synthesis that has fallen behind the pages it condenses)',
+};
+
+function parseMinorVersion(v) {
+  const [major, minor] = String(v).split('.').map(Number);
+  return { major, minor: Number.isFinite(minor) ? minor : 0 };
+}
+
+function compareMinorVersions(a, b) {
+  return a.major - b.major || a.minor - b.minor;
+}
+
+// Returns one line per version strictly after `installed` and up to and
+// including `current`, oldest first. `deltas` defaults to the real map above;
+// tests pass their own to exercise the multi-version stepping logic without
+// depending on how many real bumps have landed.
+export function schemaVersionDeltas(installed, current, deltas = SCHEMA_VERSION_DELTAS) {
+  if (!installed || !current) return [];
+  const from = parseMinorVersion(installed);
+  const to = parseMinorVersion(current);
+  if (compareMinorVersions(to, from) <= 0) return [];
+  return Object.keys(deltas)
+    .map((v) => ({ v, mv: parseMinorVersion(v) }))
+    .filter(({ mv }) => compareMinorVersions(mv, from) > 0 && compareMinorVersions(mv, to) <= 0)
+    .sort((a, b) => compareMinorVersions(a.mv, b.mv))
+    .map(({ v }) => `${v}: ${deltas[v]}`);
+}

package/scripts/uninstall.mjs

@@ -51,7 +51,7 @@ import {
   statSync,
   realpathSync,
 } from 'fs';
-import { join } from 'path';
+import { join, resolve, sep } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import {
@@ -74,7 +74,12 @@ import {
   hasSymlinkAncestor,
   buildHookCommand,
 } from './lib/extensions.mjs';
-import { removeProvenanceSidecar } from './lib/pkg-provenance.mjs';
+import {
+  removeProvenanceSidecar,
+  readProvenanceSidecar,
+  provenancePath,
+} from './lib/pkg-provenance.mjs';
+import { loadHookInventory } from './lib/hook-inventory.mjs';
 import {
   hooksDirForInstall,
   unsafeHookTargetReason,
@@ -94,12 +99,6 @@ const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..');
 
-// Shown after every fatal package-integrity error. These conditions mean the
-// shipped hooks/hooks.json is missing or malformed — never a user mistake —
-// so the only useful next step is a re-install of the package.
-const PKG_INTEGRITY_HINT =
-  '→ This indicates a corrupt or incomplete install. Re-install with `npm install -g hypomnema` (or re-install the Claude Code plugin).';
-
 function removeCommands(apply, force) {
   const targetDir = join(HOME, '.claude', 'commands', 'hypo');
   const pkgPath = join(HOME, '.claude', 'hypo-pkg.json');
@@ -725,53 +724,60 @@ function parseArgs(argv) {
   return args;
 }
 
-// ── hook map (single source of truth) ───────────────────────────────────────
-
-function loadHookFiles() {
-  let cfg;
-  try {
-    cfg = JSON.parse(readFileSync(join(PKG_ROOT, 'hooks', 'hooks.json'), 'utf-8'));
-  } catch {
-    console.error('Error: cannot read hooks/hooks.json');
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-  if (!cfg?.hooks || typeof cfg.hooks !== 'object' || Array.isArray(cfg.hooks)) {
-    console.error('Error: hooks/hooks.json must contain a "hooks" object');
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-
-  const hookFiles = new Set();
-  const normalizedHookMap = {};
-
-  for (const [event, groups] of Object.entries(cfg.hooks)) {
-    const filenames = [];
-    for (const entry of groups) {
-      if (typeof entry === 'string') {
-        // legacy flat format: entry is a filename
-        hookFiles.add(entry);
-        filenames.push(entry);
-      } else if (entry && Array.isArray(entry.hooks)) {
-        // current group format: extract filename from command string
-        for (const h of entry.hooks) {
-          if (h.type === 'command' && typeof h.command === 'string') {
-            const m = h.command.match(/\/hooks\/([^/\s]+\.mjs)$/);
-            if (m) {
-              hookFiles.add(m[1]);
-              filenames.push(m[1]);
-            }
-          }
-        }
-      }
-    }
-    normalizedHookMap[event] = filenames;
+// ── hook file set (single source of truth, with a provenance fallback) ──────
+//
+// The normal path reads PKG_ROOT's own hooks.json/shared.json through
+// loadHookInventory (scripts/lib/hook-inventory.mjs) — the same parser every
+// install/uninstall consumer shares, so a command shape one of them would
+// accept (or a trailing-argument command this file's own old `/hooks/(...)$`
+// anchor silently ignored) cannot read differently here.
+//
+// But uninstall is the one command whose whole point is letting someone leave
+// even when the package itself is broken. The other four consumers fail closed
+// on a malformed hooks.json; refusing to run here instead would trade "a few
+// files linger" for "you cannot remove this at all". So when the package list
+// cannot be read, this falls back to the provenance sidecar THIS hooksDir's own
+// last install/upgrade wrote: writeProvenanceSidecar (lib/pkg-provenance.mjs)
+// records `managedFiles`, the exact basename set that run copied, so a hooks.json
+// broken in the CURRENTLY-INSTALLED package does not strand the files a PAST,
+// working package put there.
+//
+// Only when neither the package list nor a provenance record is available does
+// this give up on identifying anything here as ours — `source: 'none'` below
+// never guesses at deletion; the caller names what remains and reports failure
+// via its exit code rather than silently succeeding at nothing.
+function resolveHookFileSet(pkgRoot, hooksDir) {
+  const inv = loadHookInventory(pkgRoot);
+  if (inv.ok) {
+    const files = new Set([...Object.values(inv.hookMap).flat(), ...inv.shared]);
+    return { files, source: 'package', warning: null };
   }
-
-  if (Array.isArray(cfg.shared)) {
-    for (const f of cfg.shared) hookFiles.add(f);
+  const sidecar = readProvenanceSidecar(hooksDir);
+  if (sidecar && Array.isArray(sidecar.managedFiles) && sidecar.managedFiles.length > 0) {
+    return {
+      files: new Set(sidecar.managedFiles),
+      source: 'provenance',
+      warning:
+        `hooks/hooks.json could not be read (${inv.error}). Recovered the managed file list for ` +
+        `${hooksDir} from ${provenancePath(hooksDir)} (recorded at the last install/upgrade) instead.`,
+    };
   }
-  return { hookMap: normalizedHookMap, hookFiles };
+  const present = existsSync(hooksDir)
+    ? readdirSync(hooksDir).filter((f) => f.endsWith('.mjs'))
+    : [];
+  return {
+    files: new Set(),
+    source: 'none',
+    warning:
+      `hooks/hooks.json could not be read (${inv.error}) and no provenance record exists at ` +
+      `${provenancePath(hooksDir)} to recover a managed file list from (an install made before ` +
+      `this sidecar field existed never wrote one). Hook file removal for ${hooksDir} is skipped ` +
+      'entirely.' +
+      (present.length
+        ? ` The following .mjs files are still there and were not evaluated — remove them by ` +
+          `hand after checking what they are: ${present.join(', ')}`
+        : ' No .mjs files were found there either.'),
+  };
 }
 
 // ── hook file removal ────────────────────────────────────────────────────────
@@ -779,8 +785,22 @@ function loadHookFiles() {
 function removeHookFiles(hooksDir, hookFiles, apply) {
   const removed = [],
     missing = [];
+  const skipped = [];
+  // Every name here comes out of a file on disk: hooks.json's event map and
+  // hooks/shared.json. A name is supposed to be a bare basename, but nothing
+  // upstream forces that, and join() resolves `../x.mjs` straight out of the
+  // hooks directory. This function DELETES what it is handed, so it confirms
+  // the containment itself rather than trusting the list it was given. An
+  // out-of-tree name is skipped and named, never removed: a corrupt list is a
+  // reason to leave files alone, not to delete somewhere else.
+  const root = resolve(hooksDir);
+  const inside = (p) => p === root || p.startsWith(root + sep);
   for (const file of hookFiles) {
     const p = join(hooksDir, file);
+    if (!inside(resolve(p))) {
+      skipped.push(file);
+      continue;
+    }
     if (existsSync(p)) {
       if (apply) rmSync(p);
       removed.push(p);
@@ -788,6 +808,12 @@ function removeHookFiles(hooksDir, hookFiles, apply) {
       missing.push(p);
     }
   }
+  if (skipped.length > 0) {
+    console.warn(
+      `Warning: ${skipped.length} hook name(s) resolve outside ${hooksDir} and were left alone: ` +
+        `${skipped.join(', ')}. Remove them by hand after checking what they are.`,
+    );
+  }
   // .hypo-provenance.json (scripts/lib/pkg-provenance.mjs) is written next to
   // this exact hooksDir by installHooks/applyHookFiles — same lifecycle as the
   // hook files themselves, so it is removed in the same pass rather than left
@@ -804,7 +830,13 @@ function removeHookFiles(hooksDir, hookFiles, apply) {
 
 // ── settings.json cleanup ────────────────────────────────────────────────────
 
-function stripSettingsJson(settingsPath, hooksDir, hookMap, apply) {
+// `hookFiles` is a flat Set of basenames (not a per-event map): a command
+// string already names the exact hook file (`node <hooksDir>/<file>`), so
+// scoping "ours" by which event a settings.json group happens to sit under adds
+// no protection a flat membership check does not already give — and a flat set
+// is what both the normal (package) and provenance-fallback paths in
+// resolveHookFileSet actually have on hand.
+function stripSettingsJson(settingsPath, hooksDir, hookFiles, apply) {
   if (!existsSync(settingsPath)) return { stripped: [], kept: 0 };
 
   let settings;
@@ -816,18 +848,18 @@ function stripSettingsJson(settingsPath, hooksDir, hookMap, apply) {
 
   if (!settings.hooks || typeof settings.hooks !== 'object') return { stripped: [], kept: 0 };
 
+  const expectedCmds = new Set(
+    [...hookFiles].map((file) => `node ${hooksDir.replace(HOME, '$HOME')}/${file}`),
+  );
+  const isHypoHook = (h) =>
+    h.type === 'command' && typeof h.command === 'string' && expectedCmds.has(h.command);
+
   const stripped = [];
   let changed = false;
 
   for (const [event, groups] of Object.entries(settings.hooks)) {
     if (!Array.isArray(groups)) continue;
 
-    const managed = hookMap[event] ?? [];
-    const isHypoHook = (h) =>
-      h.type === 'command' &&
-      typeof h.command === 'string' &&
-      managed.some((file) => h.command === `node ${hooksDir.replace(HOME, '$HOME')}/${file}`);
-
     const filtered = groups.flatMap((group) => {
       if (!Array.isArray(group.hooks)) return [group];
 
@@ -873,13 +905,31 @@ if (args.hooksDir && !args.keepShell && !args.keepWikiHook) {
   );
 }
 
-const { hookMap, hookFiles } = loadHookFiles();
-
 const claudeHooksDir = args.hooksDir ?? join(HOME, '.claude', 'hooks');
 const claudeSettings = join(HOME, '.claude', 'settings.json');
 
-const hookResult = removeHookFiles(claudeHooksDir, hookFiles, args.apply);
-const settingsResult = stripSettingsJson(claudeSettings, claudeHooksDir, hookMap, args.apply);
+// A `source: 'none'` resolution (package unreadable AND no provenance record)
+// means hook-file removal for that target was skipped entirely rather than
+// guessed at — this run must not report plain success in that case. Collected
+// across both targets and applied to the exit code once the whole report is
+// printed, so the caller still sees everything else this run did (or would do).
+let hardFailure = false;
+function reportHookSetWarning(set) {
+  if (!set.warning) return;
+  console.error(`Warning: ${set.warning}`);
+  if (set.source === 'none') hardFailure = true;
+}
+
+const claudeHookSet = resolveHookFileSet(PKG_ROOT, claudeHooksDir);
+reportHookSetWarning(claudeHookSet);
+
+const hookResult = removeHookFiles(claudeHooksDir, claudeHookSet.files, args.apply);
+const settingsResult = stripSettingsJson(
+  claudeSettings,
+  claudeHooksDir,
+  claudeHookSet.files,
+  args.apply,
+);
 const commandResult = removeCommands(args.apply, args.forceCommands);
 
 // Wiki-side cleanup: the git pre-commit hook and the shell rc block init.mjs
@@ -946,8 +996,15 @@ let codexExtSettings = { stripped: [] };
 if (args.codex) {
   const codexHooksDir = join(HOME, '.codex', 'hooks');
   const codexSettings = join(HOME, '.codex', 'settings.json');
-  codexHookResult = removeHookFiles(codexHooksDir, hookFiles, args.apply);
-  codexSettingsResult = stripSettingsJson(codexSettings, codexHooksDir, hookMap, args.apply);
+  const codexHookSet = resolveHookFileSet(PKG_ROOT, codexHooksDir);
+  reportHookSetWarning(codexHookSet);
+  codexHookResult = removeHookFiles(codexHooksDir, codexHookSet.files, args.apply);
+  codexSettingsResult = stripSettingsJson(
+    codexSettings,
+    codexHooksDir,
+    codexHookSet.files,
+    args.apply,
+  );
   codexExtResult = removeExtensions('codex', args.apply, args.forceExtensions);
   codexExtSettings = stripExtensionSettings(
     codexSettings,
@@ -1105,3 +1162,10 @@ if (
 }
 
 console.log(lines.join('\n\n'));
+
+// See resolveHookFileSet / reportHookSetWarning above (major D): neither the
+// package's own hooks.json nor a provenance record could identify what to
+// remove for at least one target. The report above already named what remains;
+// this is what tells an automated caller (or a script chaining onto this one)
+// that the run did not fully succeed, rather than exiting 0 on a silent skip.
+if (hardFailure) process.exit(1);