create-claude-cabinet 0.46.0 → 0.47.0

package/lib/copy.js

@@ -50,17 +50,71 @@ function recordSkip(manifest, key, { identical = false, incomingHash = null } =
   }
 }
 
+/**
+ * Files shipped as STARTER content but owned by the project the moment they
+ * land. The installer seeds them if absent, NEVER overwrites them, and NEVER
+ * records them in the manifest. Manifest presence means "CC-owned", which has
+ * two consequences a project-owned file must avoid: cc-upstream-guard blocks
+ * edits to it, and a `--yes` reinstall silently overwrites it. The recordSkip
+ * "identical → keep tracked" rule is content-based and so still recorded an
+ * UNEDITED seed in the manifest — which false-blocked the very first edit (a
+ * project-owned file is unedited exactly until someone edits it). These files
+ * are project-owned by DECLARATION, not by content divergence.
+ *
+ * Keyed by basename: there is one such seed today and the src→dest relPath
+ * mapping varies by call site, so a basename match is the robust check.
+ * `directives-project.yaml`'s own header says it is "NOT overwritten by the
+ * installer ... extend upstream members with project-specific mandates" —
+ * recording it as CC-owned false-blocked the exact edits it exists to receive
+ * (field incident 2026-06-17, act:2001bf54).
+ */
+const PROJECT_OWNED_SEED_BASENAMES = new Set(['directives-project.yaml']);
+function isProjectOwnedSeed(relPath) {
+  return PROJECT_OWNED_SEED_BASENAMES.has(path.basename(relPath));
+}
+
+/**
+ * The canonical FREEZE rule for an EXISTING file in a frozen module that
+ * differs from the incoming template (act:c1013967). Shared by both copy
+ * paths — copy.js's directory walk and cli.js's single-file branch — so the
+ * "third ownership state" is defined in exactly one place (the recordSkip
+ * precedent).
+ *
+ * Freeze is "CC-owned but temporarily pinned": the file is NOT overwritten,
+ * and — crucially — only a file that is ALREADY CC-owned (present in the prior
+ * manifest) is RETAINED in the new manifest, at its ON-DISK hash. Two reasons
+ * the on-disk hash is the only correct choice:
+ *   - It keeps the file PRESENT in the manifest, so the upstream-cleanup loop
+ *     never lists it for deletion (a frozen file dropped from allManifest would
+ *     be deleted — the exact opposite of freeze).
+ *   - On-disk == recorded keeps the value-comparison consumers green:
+ *     cc-drift-check sees no drift, reset.js classifies it unmodified.
+ *
+ * A frozen-module file that differs but is NOT already CC-owned is
+ * project-owned (project-created or a kept/edited file deliberately omitted
+ * from the manifest). Freeze adds nothing for it — it's already never
+ * overwritten — so it must FALL THROUGH to the normal skip-and-omit path.
+ * RETAINING it would adopt a project-owned file into the manifest and clobber
+ * it on the unfreeze reinstall (violates the recordSkip invariant above).
+ *
+ * @returns {{manifestHash: string}}  retain at on-disk hash (CC-owned)
+ *        | {{omit: true}}            fall through to skip-and-omit (project-owned)
+ */
+function freezeRetain({ existing, isCcOwned }) {
+  return isCcOwned ? { manifestHash: hashContent(existing) } : { omit: true };
+}
+
 /**
  * Recursively copy files from src to dest, surfacing conflicts.
  * Returns { copied: string[], skipped: string[], overwritten: string[] }
  */
-async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false, projectRoot = null, existingManifest = {}, instructionPhases = new Set() } = {}) {
-  const results = { copied: [], skipped: [], overwritten: [], manifest: {} };
-  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases);
+async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false, projectRoot = null, existingManifest = {}, instructionPhases = new Set(), frozen = false } = {}) {
+  const results = { copied: [], skipped: [], overwritten: [], manifest: {}, frozen: [] };
+  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases, frozen);
   return results;
 }
 
-async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases) {
+async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases, frozen) {
   const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -80,11 +134,32 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
       if (!dryRun && !fs.existsSync(destPath)) {
         fs.mkdirSync(destPath, { recursive: true });
       }
-      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases);
+      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest, instructionPhases, frozen);
     } else {
       const incoming = fs.readFileSync(srcPath, 'utf8');
       const incomingHash = hashContent(incoming);
 
+      // Project-owned seed (act:2001bf54): seed if absent, never overwrite,
+      // and ALWAYS omit from the manifest — recording it would let
+      // cc-upstream-guard block edits and a --yes reinstall clobber the
+      // consumer's content. Runs before any existsSync branch so neither the
+      // byte-identical path (which would re-record an unedited seed) nor the
+      // manifest-driven overwrite path can reach it.
+      if (isProjectOwnedSeed(relPath)) {
+        if (!fs.existsSync(destPath)) {
+          if (!dryRun) {
+            const dir = path.dirname(destPath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            fs.copyFileSync(srcPath, destPath);
+          }
+          results.copied.push(relPath);
+        } else {
+          results.skipped.push(relPath);
+        }
+        recordSkip(results.manifest, relPath); // omit — project-owned by declaration
+        continue;
+      }
+
       if (fs.existsSync(destPath)) {
         const existing = fs.readFileSync(destPath, 'utf8');
 
@@ -112,6 +187,24 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
           continue;
         }
 
+        // Frozen module (act:c1013967): the file differs and is past the
+        // identical + seed + customized-phase guards, so it is a CC-managed
+        // file that WOULD be overwritten. Hold it instead. Only a file already
+        // CC-owned (in the prior manifest) is retained at its on-disk hash; a
+        // project-owned file falls through to the normal skip-and-omit path.
+        if (frozen) {
+          const manifestKey = projectRoot ? path.relative(projectRoot, destPath) : relPath;
+          const decision = freezeRetain({ existing, isCcOwned: Boolean(existingManifest[manifestKey]) });
+          if (decision.manifestHash) {
+            results.skipped.push(relPath);
+            results.frozen.push(relPath);
+            results.manifest[relPath] = decision.manifestHash;
+            console.log(`  ❄ Frozen (held): ${displayPath}`);
+            continue;
+          }
+          // decision.omit → project-owned; fall through.
+        }
+
         if (skipConflicts) {
           // Check if file is upstream-managed (in the old manifest).
           // If so, overwrite — it can't be customized (hook enforces this).
@@ -177,6 +270,15 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
           recordSkip(results.manifest, relPath);
         }
       } else {
+        // New file in a frozen module: hold it back so the on-disk module
+        // stays internally consistent at its pinned version. Report only — no
+        // manifest entry (there's no on-disk content to hash; a phantom entry
+        // would break cc-drift-check/cleanup). On unfreeze this branch creates it.
+        if (frozen) {
+          results.frozen.push(relPath);
+          console.log(`  ❄ Frozen (held new): ${displayPath}`);
+          continue;
+        }
         if (!dryRun) {
           const dir = path.dirname(destPath);
           if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -215,4 +317,4 @@ function showDiff(existing, incoming, relPath) {
   console.log('');
 }
 
-module.exports = { copyTemplates, recordSkip };
+module.exports = { copyTemplates, recordSkip, isProjectOwnedSeed, freezeRetain };

package/lib/db-setup.js

@@ -1,46 +1,151 @@
 const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const metadata = require('./metadata');
+
+// Substrings that identify a better-sqlite3 native-module ABI mismatch —
+// the compiled .node binary was built under a different Node than the one
+// running `pib-db.mjs init`. Node surfaces this as an ERR_DLOPEN_FAILED
+// with a NODE_MODULE_VERSION line; field reports during consumer walks
+// also showed the shorter "native module version mismatch" phrasing.
+const ABI_MISMATCH_SIGNATURES = [
+  'NODE_MODULE_VERSION',
+  'different Node.js version',
+  'was compiled against',
+  'native module version mismatch',
+  'ERR_DLOPEN_FAILED',
+];
+
+function isAbiMismatch(text) {
+  const s = String(text || '');
+  return ABI_MISMATCH_SIGNATURES.some((sig) => s.includes(sig));
+}
+
+// Read the bundled pib-db schema version from the (already-copied)
+// pib-db-lib.mjs as TEXT — never by importing it, so learning the version
+// does not itself load better-sqlite3. Returns a number, or null when the
+// file is missing or the constant can't be parsed.
+function readBundledSchemaVersion(scriptsDir) {
+  try {
+    const src = fs.readFileSync(path.join(scriptsDir, 'pib-db-lib.mjs'), 'utf8');
+    const m = src.match(/SCHEMA_VERSION\s*=\s*(\d+)/);
+    return m ? Number(m[1]) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Lazy-init gate: a reinstall whose recorded schema version already matches
+// the bundled one (and whose pib.db exists) needs no migration, so the init
+// step can be skipped entirely — and a skipped init never loads the
+// (possibly stale) native module. Conservative by construction: any
+// missing/unequal input returns false, so we only skip when certain there
+// is nothing to migrate.
+function shouldSkipInit({ dbExists, recordedVersion, bundledVersion }) {
+  return Boolean(
+    dbExists &&
+    bundledVersion != null &&
+    recordedVersion != null &&
+    recordedVersion === bundledVersion
+  );
+}
 
 /**
  * Set up the PIB database in the target project.
- * - Copies pib-db.mjs and schema to scripts/
+ * - Copies are already in place (scripts/ copied by the main install loop)
  * - Runs npm init if no package.json
- * - Installs better-sqlite3
- * - Runs pib-db init
+ * - Installs better-sqlite3 if absent
+ * - Initializes/migrates the database, UNLESS the schema is already current
+ *   (lazy-init), and self-heals an ABI-mismatched native binary.
+ *
+ * Returns { results: string[], schemaVersion: number|null }. schemaVersion
+ * is the applied (or confirmed-current) schema version when init succeeded
+ * or was correctly skipped, and null when init could not complete (ABI
+ * mismatch with no working rebuild) — so the caller never records a false
+ * "schema current" claim in .ccrc.json.
+ *
+ * `opts.exec` and `opts.log` are injectable for testing; they default to
+ * execSync and console.log.
  */
-function setupDb(projectDir) {
+function setupDb(projectDir, opts = {}) {
+  const exec = opts.exec || ((cmd, o) => execSync(cmd, o));
+  const log = opts.log || console.log;
   const scriptsDir = path.join(projectDir, 'scripts');
   const results = [];
 
   // Check if package.json exists; if not, init
   const pkgPath = path.join(projectDir, 'package.json');
   if (!fs.existsSync(pkgPath)) {
-    console.log('  Initializing package.json...');
-    execSync('npm init -y', { cwd: projectDir, stdio: 'pipe' });
+    log('  Initializing package.json...');
+    exec('npm init -y', { cwd: projectDir, stdio: 'pipe' });
     results.push('Created package.json');
   }
 
   // pib-db.mjs uses ESM imports — .mjs extension lets Node treat it as ESM
   // regardless of the project's package.json type field
+  const dbScript = path.join(scriptsDir, 'pib-db.mjs');
+  const dbPath = path.join(projectDir, 'pib.db');
+  const bundledVersion = readBundledSchemaVersion(scriptsDir);
+
+  // Lazy-init: skip when the schema is already current. This is the common
+  // reinstall case; skipping means a no-migration release never loads
+  // better-sqlite3, so a stale native binary can't wall the install with an
+  // ABI-mismatch error it never needed to risk.
+  const existingMeta = metadata.read(projectDir) || {};
+  if (
+    shouldSkipInit({
+      dbExists: fs.existsSync(dbPath),
+      recordedVersion: existingMeta.dbSchemaVersion,
+      bundledVersion,
+    })
+  ) {
+    results.push(`Database schema already current (v${bundledVersion}) — skipped init`);
+    return { results, schemaVersion: bundledVersion };
+  }
 
-  // Install better-sqlite3 if not already installed
+  // Install better-sqlite3 if not already installed. A pre-existing but
+  // stale binary is left for the rebuild path below to heal — a plain
+  // reinstall wouldn't change an already-satisfied semver.
   const nodeModules = path.join(projectDir, 'node_modules', 'better-sqlite3');
   if (!fs.existsSync(nodeModules)) {
-    console.log('  Installing better-sqlite3...');
-    execSync('npm install better-sqlite3', { cwd: projectDir, stdio: 'pipe' });
+    log('  Installing better-sqlite3...');
+    exec('npm install better-sqlite3', { cwd: projectDir, stdio: 'pipe' });
     results.push('Installed better-sqlite3');
   }
 
-  // Initialize the database
-  const dbScript = path.join(scriptsDir, 'pib-db.mjs');
-  if (fs.existsSync(dbScript)) {
-    console.log('  Initializing database...');
-    execSync(`node ${dbScript} init`, { cwd: projectDir, stdio: 'pipe' });
-    results.push('Initialized pib.db');
+  if (!fs.existsSync(dbScript)) {
+    return { results, schemaVersion: null };
   }
 
-  return results;
+  log('  Initializing database...');
+  try {
+    exec(`node ${dbScript} init`, { cwd: projectDir, stdio: 'pipe' });
+    results.push('Initialized pib.db');
+    return { results, schemaVersion: bundledVersion };
+  } catch (err) {
+    const detail = `${String(err.stderr || '')}\n${String(err.message || '')}`;
+    // Non-ABI failures keep their old handling — propagate to the caller's
+    // existing "Database setup failed" catch.
+    if (!isAbiMismatch(detail)) throw err;
+
+    // ABI mismatch: rebuild the native binary once and retry. If that
+    // works, the install self-heals. If it doesn't, fall back to a single
+    // actionable line — never a stack trace, never a silent skip.
+    log('  better-sqlite3 built for a different Node — rebuilding once and retrying...');
+    try {
+      exec('npm rebuild better-sqlite3', { cwd: projectDir, stdio: 'pipe' });
+      exec(`node ${dbScript} init`, { cwd: projectDir, stdio: 'pipe' });
+      results.push('Rebuilt better-sqlite3 (ABI mismatch) and initialized pib.db');
+      return { results, schemaVersion: bundledVersion };
+    } catch {
+      results.push(
+        'DB step skipped: better-sqlite3 was built for a different Node. Run ' +
+          '`npm rebuild better-sqlite3` then `node scripts/pib-db.mjs init` in ' +
+          'this project — your existing pib.db is untouched.'
+      );
+      return { results, schemaVersion: null };
+    }
+  }
 }
 
-module.exports = { setupDb };
+module.exports = { setupDb, isAbiMismatch, readBundledSchemaVersion, shouldSkipInit };

package/lib/metadata.js

@@ -44,7 +44,7 @@ function merge(projectDir, partial) {
   return data;
 }
 
-function create(projectDir, { modules, skipped, version, manifest = {} }) {
+function create(projectDir, { modules, skipped, version, manifest = {}, dbSchemaVersion } = {}) {
   // Read existing first so unknown top-level keys (e.g.
   // `migrated_from_omega` set by --migrate-memory) survive the
   // install/upgrade rewrite. Only the install-specific fields below
@@ -60,6 +60,13 @@ function create(projectDir, { modules, skipped, version, manifest = {} }) {
     manifest,
   };
 
+  // Record the applied pib-db schema version when this install confirmed
+  // one (init ran or was skipped as already-current). When it didn't
+  // (--no-db, dry-run, or an unhealed ABI mismatch), `dbSchemaVersion` is
+  // undefined and any prior value rides through via `...existing` — we
+  // never claim "schema current" off the back of a skipped/failed init.
+  if (dbSchemaVersion != null) data.dbSchemaVersion = dbSchemaVersion;
+
   for (const mod of modules) {
     data.modules[mod] = true;
   }
@@ -71,4 +78,46 @@ function create(projectDir, { modules, skipped, version, manifest = {} }) {
   return data;
 }
 
-module.exports = { read, write, merge, create, metadataPath, METADATA_FILE };
+/**
+ * Read the project's frozen-module list from `.ccrc.json`. Returns a
+ * normalized, deduped `string[]` of module keys the operator has pinned
+ * (the temporary, manifest-RETAINING third ownership state — act:c1013967).
+ *
+ * Defensive by construction: a non-array `frozenModules` (shape drift) reads
+ * as "nothing frozen" rather than throwing, and a genuinely-absent `.ccrc.json`
+ * returns `[]`. It deliberately does NOT swallow a JSON parse error — `read()`
+ * throws on a malformed `.ccrc.json`, which HALTS the reinstall. That fail-
+ * closed behavior is the point: when the freeze state can't be read, the
+ * installer must stop, never proceed as if nothing were frozen (which would
+ * silently rewrite the very files a freeze exists to protect).
+ */
+function readFrozenModules(projectDir) {
+  const m = read(projectDir);
+  const raw = m && m.frozenModules;
+  if (!Array.isArray(raw)) return [];
+  return [...new Set(raw.filter((x) => typeof x === 'string'))];
+}
+
+/**
+ * Persist the frozen-module list, shallow-merged into `.ccrc.json` so every
+ * other field (manifest, modules, dbSchemaVersion, …) rides through. Input is
+ * normalized to a deduped string[]. Returns the written array.
+ */
+function setFrozenModules(projectDir, mods) {
+  const normalized = Array.isArray(mods)
+    ? [...new Set(mods.filter((x) => typeof x === 'string'))]
+    : [];
+  merge(projectDir, { frozenModules: normalized });
+  return normalized;
+}
+
+module.exports = {
+  read,
+  write,
+  merge,
+  create,
+  metadataPath,
+  METADATA_FILE,
+  readFrozenModules,
+  setFrozenModules,
+};

package/lib/settings-merge.js

@@ -8,7 +8,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/git-guardrails.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/git-guardrails.sh',
         },
       ],
     },
@@ -17,7 +17,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/work-tracker-guard.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/work-tracker-guard.sh',
         },
       ],
     },
@@ -26,7 +26,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/cc-upstream-guard.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/cc-upstream-guard.sh',
         },
       ],
     },
@@ -35,7 +35,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/action-quality-gate.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/action-quality-gate.sh',
         },
       ],
     },
@@ -44,7 +44,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/action-completion-gate.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/action-completion-gate.sh',
         },
       ],
     },
@@ -55,7 +55,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/skill-telemetry.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/skill-telemetry.sh',
         },
       ],
     },
@@ -66,7 +66,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/skill-tool-telemetry.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/skill-tool-telemetry.sh',
         },
       ],
     },
@@ -75,7 +75,7 @@ const DEFAULT_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/memory-index-guard.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/memory-index-guard.sh',
         },
       ],
     },
@@ -133,7 +133,7 @@ const BASH_COMPRESS_HOOKS = {
       hooks: [
         {
           type: 'command',
-          command: '.claude/hooks/bash-output-compress.sh',
+          command: '$CLAUDE_PROJECT_DIR/.claude/hooks/bash-output-compress.sh',
         },
       ],
     },
@@ -156,6 +156,38 @@ const LEGACY_HOOK_COMMANDS = [
   'domain-memories.sh',
 ];
 
+// CC-owned hook commands ship with a `$CLAUDE_PROJECT_DIR/` prefix so they
+// resolve regardless of the hook's working directory. Older installs wrote them
+// bare-relative (`.claude/hooks/X.sh`), which break ("No such file or
+// directory") whenever a hook fires from a non-root cwd. bareForm() derives that
+// legacy spelling so a reinstall can REPLACE it (drop old, add prefixed) rather
+// than leave a broken duplicate.
+function bareForm(command) {
+  return (command || '').replace(/^\$CLAUDE_PROJECT_DIR\//, '');
+}
+
+// Every CC-owned hook command in a hook set, in its current spelling.
+function ccHookCommands(hookSet) {
+  return Object.values(hookSet)
+    .flatMap(entries => entries.flatMap(e => (e.hooks || []).map(h => h.command)));
+}
+
+// Remove every sub-hook whose command exactly matches one of `commands`, and
+// prune entries left empty. Exact-match on CC-owned command strings only — a
+// consumer's own hooks (different paths) are never touched.
+function dropHookCommands(settings, commands) {
+  const drop = new Set(commands.filter(Boolean));
+  for (const [event, entries] of Object.entries(settings.hooks || {})) {
+    if (!Array.isArray(entries)) continue;
+    settings.hooks[event] = entries
+      .map(entry => (entry.hooks && Array.isArray(entry.hooks))
+        ? { ...entry, hooks: entry.hooks.filter(h => !drop.has(h.command)) }
+        : entry)
+      .filter(entry => !entry.hooks || !Array.isArray(entry.hooks) || entry.hooks.length > 0);
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+}
+
 /**
  * Merge PIB hooks into the project's .claude/settings.json.
  * Creates the file if it doesn't exist. Preserves existing hooks.
@@ -199,6 +231,13 @@ function mergeSettings(projectDir, { includeDb = true } = {}) {
     if (!settings.hooks[event]) continue;
   }
 
+  // Retire superseded bare-relative CC hooks so the $CLAUDE_PROJECT_DIR-prefixed
+  // forms below REPLACE them rather than duplicate. A bare `.claude/hooks/X.sh`
+  // only resolves when the hook runs from the project root; it errors ("No such
+  // file or directory") from any other cwd. Exact-match drop on CC-owned
+  // commands — consumer-authored hooks are left intact.
+  dropHookCommands(settings, ccHookCommands(DEFAULT_HOOKS).map(bareForm));
+
   // Merge each hook event type from DEFAULT_HOOKS
   for (const [event, newHooks] of Object.entries(DEFAULT_HOOKS)) {
     if (!settings.hooks[event]) {
@@ -254,7 +293,7 @@ function healUserSettings() {
     const filtered = entries.filter(entry => {
       if (!entry.hooks || !Array.isArray(entry.hooks)) return true;
       const hasRelativeCcHook = entry.hooks.some(h =>
-        /^\.claude\/hooks\//.test(h.command || '')
+        /^(\$CLAUDE_PROJECT_DIR\/)?\.claude\/hooks\//.test(h.command || '')
       );
       if (hasRelativeCcHook) removed++;
       return !hasRelativeCcHook;
@@ -338,6 +377,9 @@ function mergeBashCompressHooks(settingsPath) {
   const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
   if (!settings.hooks) settings.hooks = {};
 
+  // Replace any superseded bare-relative form with the prefixed one (see mergeSettings).
+  dropHookCommands(settings, ccHookCommands(BASH_COMPRESS_HOOKS).map(bareForm));
+
   for (const [event, newHooks] of Object.entries(BASH_COMPRESS_HOOKS)) {
     if (!settings.hooks[event]) {
       settings.hooks[event] = newHooks;

package/lib/watchtower-setup.js

@@ -76,6 +76,7 @@ function buildManagedFiles() {
   const shellRunners = [
     'watchtower-ring1-runner.sh',
     'watchtower-ring2-runner.sh',
+    'watchtower-ring4-runner.sh',
     'watchtower-status.sh',
   ];
   for (const name of shellRunners) {
@@ -168,8 +169,27 @@ function refreshWatchtowerRuntime(opts = {}) {
     const content = fs.readFileSync(file.src);
     const hash = sha256(content);
 
-    if (manifest.files[file.dest] === hash) {
-      continue; // file unchanged
+    // Content-aware skip: compare the template hash to the runtime file's
+    // ACTUAL on-disk bytes, NOT the cached manifest. The manifest can lie — a
+    // hand-edited or externally-replaced runtime file still carries the hash
+    // the manifest recorded at last write, so a manifest-only check would skip
+    // it and leave the divergence running. Reading the real file makes the
+    // refresh self-healing: any runtime file that differs from the template
+    // (or is missing) is rewritten, so a reinstall reliably reconverges the
+    // runtime onto the template instead of silently leaving it stale.
+    let runtimeHash = null;
+    if (fs.existsSync(file.dest)) {
+      try {
+        runtimeHash = sha256(fs.readFileSync(file.dest));
+      } catch {
+        runtimeHash = null; // unreadable runtime file → treat as divergent
+      }
+    }
+
+    if (runtimeHash === hash) {
+      // Already in sync on disk. Keep the manifest honest as bookkeeping.
+      if (!dryRun) manifest.files[file.dest] = hash;
+      continue;
     }
 
     if (dryRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/cabinet/advisories-state-schema.md

@@ -89,7 +89,7 @@ Document any new advisory's signal source here when you add it, and call out exp
 | `lsp:ruby` | `Gemfile` or `*.rb` | `/plugin install ruby-lsp@claude-plugins-official` (also needs `gem install ruby-lsp` AND `ENABLE_LSP_TOOL=1`) |
 | `mcp:railway` | `railway.toml` and no railway key in `~/.claude.json` (no-probe) | local: `railway setup agent -y` · remote: register `mcp.railway.com` (OAuth) |
 | `plugin:hookify` | `.claude/rules/enforcement-pipeline.md` exists and hookify not in `claude plugin list` (signal is **static**; probe-gated) | `/plugin install hookify` |
-| `briefing-file` | `.claude/briefing/_briefing.md` is **absent** (signal `missing`, **static**; no-probe) | run `/onboard` to create one |
+| `briefing-file` | `.claude/cabinet/_briefing.md` is **absent** (canonical location — where cabinet members read; `.claude/briefing/` holds only installer-seeded templates) (signal `missing`, **static**; no-probe) | run `/onboard` to create one |
 | `registry-orphan` | `~/.claude/cc-registry.json` lists project path(s) that no longer exist (signal = sorted orphan-name set, so it re-arms when the registry changes; no-probe) | remove the dead entr(y/ies) from `~/.claude/cc-registry.json` |
 
 > Note: `mcp:railway` keys on `railway.toml`, which Ring 1 also marker-checks for deploy detection — these are independent reads of the same file for different purposes; do not consolidate them (the advisory adds the `~/.claude.json` registration predicate Ring 1 lacks).

package/templates/cabinet/checklist-stats-schema.md

@@ -19,9 +19,23 @@ state.
 | Writer | When | What |
 |--------|------|------|
 | `/execute` `post-impl-checklist` phase | every run past its no-op guard | increments `runs`; per triggered dimension increments `fires`, sets `last_fired` |
-| `/debrief` `checklist-feedback` phase | when a session bug WAS caught via a surfaced check | appends to that dimension's `catches` |
+| Ring 3 close `checklist-catch` lens (Phase 2p) | session close, when the transcript shows a surfaced check that caught a real bug | appends to that dimension's `catches` |
+| `/debrief` `checklist-feedback` phase (pre-watchtower; retiring) | when a session bug WAS caught via a surfaced check | appends to that dimension's `catches` |
 | `/audit` `checklist-pruning` phase | every pruning verdict (including "keep") | appends to `pruning_reviews` |
 
+The **catch side is recorded automatically at session close** by the
+Ring 3 `checklist-catch` lens (`watchtower-ring3-close.mjs`, Phase 2p)
+for watchtower-installed projects — it reads the transcript, attributes
+catches to a named dimension, and writes them via the protocol below.
+`/debrief`'s `checklist-feedback` phase did this interactively and is
+retired by the watchtower burn-in (its sharpening side — proposing new
+checks for bugs that *slipped through* — needs operator approval and
+cannot move to a background ring; only the catch tally moved). The two
+writers are mutually exclusive in practice: a watchtower project closes
+through Ring 3, a non-watchtower project through debrief, and both
+follow the same atomic, fail-open write protocol — so the catches a
+later audit prunes against are recorded the same way regardless.
+
 ## Schema (`schema_version: 1`)
 
 ```json