create-claude-cabinet 0.44.0 → 0.46.0

package/README.md

@@ -1,7 +1,7 @@
 # Claude Cabinet
 
 A cabinet of expert advisors for your Claude Code project. One command
-gives Claude a memory, 32 domain experts, a planning process, and the
+gives Claude a memory, 34 domain experts, a planning process, and the
 habit of starting sessions informed and ending them properly.
 
 Built by a guy who'd rather talk to Claude than write code. Most of it
@@ -12,7 +12,7 @@ was built by Claude. I just complained until it (mostly) worked.
 Your project gets a cabinet — specialist advisors who each own a domain
 and weigh in when their expertise matters:
 
-- **Cabinet members** — 32 domain experts (security, accessibility,
+- **Cabinet members** — 34 domain experts (security, accessibility,
   architecture, QA, etc.) who review your project and surface what
   you'd miss alone
 - **Briefings** — project context members read before weighing in
@@ -78,7 +78,7 @@ left off.
 
 ### The Cabinet (included in lean)
 
-32 expert cabinet members who each own a domain and stay in their lane.
+34 expert cabinet members who each own a domain and stay in their lane.
 **Speed-freak** watches performance. **Boundary-man** catches edge cases.
 **Record-keeper** flags when docs drift from code. **Workflow-cop**
 evaluates whether your process actually works. Each member has a
@@ -241,8 +241,13 @@ npx create-claude-cabinet --yes                   # Accept all defaults
 npx create-claude-cabinet --yes --no-db           # All defaults, skip database
 npx create-claude-cabinet --dry-run               # Preview without writing files
 npx create-claude-cabinet --modules verify --yes  # Add an opt-in module (merges, doesn't replace)
+npx create-claude-cabinet --frontier-model claude-fable-5  # Designate your frontier model (watchdog)
 ```
 
+### Frontier-model watchdog
+
+`--frontier-model <model>` records, once, which model your heavy thinking is supposed to run on. The designation is per-operator (stored in `~/.claude/cc-registry.json` under `frontierModel`, not per-project), and the installer prints the effective value on every run. From then on, `/orient` — and, on watchtower installs, the SessionStart hook — compares the session's actual model against it and leads the briefing with a loud warning on mismatch. The key can be an exact model ID (`claude-fable-5`, exact match required) or a family alias (`fable`, matches any model ID containing it). This is **visibility only**: nothing is pinned, blocked, or rerouted — it just makes "you're accidentally on the wrong model" impossible to miss. A stale key after a model-family transition nags loudly by design; update it with the same flag.
+
 ## What Gets Installed
 
 Everything goes into `.claude/` or `scripts/`. Nothing touches your
@@ -251,7 +256,7 @@ source code.
 ```
 .claude/
 ├── skills/          # orient, debrief, plan, execute, audit, etc.
-│   └── cabinet-*/   # 32 cabinet member definitions
+│   └── cabinet-*/   # 34 cabinet member definitions
 ├── cabinet/         # committees, lifecycle, composition patterns
 │                    #   (incl. pib-db-access.md, pib-db-triggers.md)
 ├── briefing/        # project briefing templates

package/lib/cli.js

@@ -3,7 +3,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 const crypto = require('crypto');
-const { copyTemplates } = require('./copy');
+const { copyTemplates, recordSkip } = require('./copy');
 const { mergeSettings, healUserSettings, mergeWatchtowerHooks, mergeMuxHooks, mergeBashCompressHooks } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
@@ -12,6 +12,7 @@ const { setupSiteAuditRuntime } = require('./site-audit-setup');
 const { setupEngagement } = require('./engagement-setup');
 const { setupMux } = require('./mux-setup');
 const { setupEngagementServer } = require('./engagement-server-setup');
+const { refreshWatchtowerRuntime } = require('./watchtower-setup');
 const { reset } = require('./reset');
 
 const VERSION = require('../package.json').version;
@@ -460,11 +461,13 @@ const MODULES = {
       'skills/orient-quick',
       'skills/debrief',
       'skills/debrief-quick',
+      'skills/session-handoff',
       // Instruction phases — always ship, overriding the default skip-phases rule in copy.js
       'skills/debrief/phases/audit-pattern-capture.md',
       'skills/debrief/phases/methodology-capture.md',
       'skills/debrief/phases/record-lessons.md',
       'skills/debrief/phases/upstream-feedback.md',
+      'skills/debrief/phases/qa-handoff-sweep.md',
       'skills/menu',
     ],
   },
@@ -491,7 +494,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: true,
-    templates: ['skills/plan', 'skills/execute', 'skills/execute/phases/post-impl-checklist.md', 'skills/debrief/phases/checklist-feedback.md', 'skills/checklist-discover', 'skills/generate-plan-groups', 'skills/execute-group', 'workflows/execute-group-implement.js', 'workflows/execute-group-complete.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md', 'cabinet/elicitation-methods.md', 'cabinet/qa-dimensions-template.yaml', 'scripts/qa-dimensions-validator.cjs', 'skills/orient/phases/checklist-status.md'],
+    templates: ['skills/plan', 'skills/execute', 'skills/execute/phases/post-impl-checklist.md', 'skills/debrief/phases/checklist-feedback.md', 'skills/checklist-discover', 'skills/generate-plan-groups', 'skills/execute-group', 'workflows/execute-group-implement.js', 'workflows/execute-group-complete.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md', 'cabinet/elicitation-methods.md', 'cabinet/qa-dimensions-template.yaml', 'cabinet/checklist-stats-schema.md', 'scripts/qa-dimensions-validator.cjs', 'skills/orient/phases/checklist-status.md', 'skills/audit/phases/checklist-pruning.md'],
   },
   'compliance': {
     name: 'Compliance Stack (rules + enforcement)',
@@ -630,6 +633,9 @@ const MODULES = {
       'cabinet/watchtower-contracts.md',
       'scripts/watchtower-lib.mjs',
       'scripts/watchtower-queue.mjs',
+      'scripts/watchtower-routines.mjs',
+      'scripts/watchtower-advisories.mjs',
+      'cabinet/advisories-state-schema.md',
       'skills/inbox',
       'hooks/watchtower-session-start.sh',
       'scripts/watchtower-build-context.mjs',
@@ -653,6 +659,7 @@ const MODULES = {
       'skills/briefing',
       'skills/threads',
       'skills/qa-handoff',
+      'skills/qa-drain',
     ],
   },
   mux: {
@@ -750,6 +757,14 @@ function parseArgs(argv) {
     else if (arg === '--modules' && i + 1 < args.length) {
       flags.modules = args[++i].split(',').map(s => s.trim()).filter(Boolean);
     }
+    else if (arg === '--frontier-model' && i + 1 < args.length) {
+      // Empty/whitespace values are treated as absent: '' is a substring of
+      // every model ID, which would match everything and leave the watchdog
+      // permanently silent while appearing configured.
+      const value = args[++i].trim();
+      if (value) flags.frontierModel = value;
+      else flags.frontierModelEmpty = true;
+    }
     else if (!arg.startsWith('-')) flags.targetDir = arg;
   }
 
@@ -775,6 +790,11 @@ function printHelp() {
                   disables omega hooks/MCP. Idempotent — safe to re-run.
                   Pair with --dry-run to preview.
     --unmigrate-memory   Roll back --migrate-memory using its backup dir.
+    --frontier-model <model>  Designate your frontier model (user-level, stored
+                  in ~/.claude/cc-registry.json). Visibility only: /orient and
+                  the watchtower SessionStart hook warn loudly when a session
+                  runs a different model. Does NOT pin or route anything.
+                  Accepts an exact ID (claude-fable-5) or a family alias (fable).
     --help, -h    Show this help
 
   Examples:
@@ -1214,7 +1234,7 @@ async function run() {
           const existingContent = fs.readFileSync(destPath, 'utf8');
           if (existingContent === incoming) {
             totalSkipped++;
-            allManifest[mPath] = incomingHash;
+            recordSkip(allManifest, mPath, { identical: true, incomingHash });
             continue;
           }
 
@@ -1230,7 +1250,9 @@ async function run() {
           if (isPhaseFile && !isInstructionPhase && existingContent.trim() !== '' && existingContent.trim() !== incoming.trim()) {
             console.log(`  Preserved customized phase: ${tmpl}`);
             totalSkipped++;
-            allManifest[mPath] = hashContent(existingContent);
+            // Customized phase = project-owned content → omit from manifest
+            // (recordSkip in copy.js — omission means "not ours").
+            recordSkip(allManifest, mPath);
             continue;
           }
 
@@ -1240,10 +1262,19 @@ async function run() {
             if (existingManifest[mPath]) {
               if (!flags.dryRun) fs.copyFileSync(srcPath, destPath);
               totalOverwritten++;
+              // Log single-file overwrites too — the directory path (copy.js)
+              // already does. Without this, scripts/ updates are invisible in
+              // install output, masking whether a changed script propagated.
+              console.log(`  Updated: ${path.relative(projectDir, destPath)}`);
+              allManifest[mPath] = incomingHash;
             } else {
               totalSkipped++;
+              // Project-created file → omit from manifest entirely. Ownership
+              // classification is manifest-PRESENCE-based, so recording ANY
+              // hash here would mark the file upstream-owned and the NEXT
+              // install would silently overwrite it (act:bf21c95b).
+              recordSkip(allManifest, mPath);
             }
-            allManifest[mPath] = incomingHash;
           } else {
             const response = await prompts({
               type: 'select',
@@ -1258,10 +1289,13 @@ async function run() {
             if (response.action === 'overwrite') {
               if (!flags.dryRun) fs.copyFileSync(srcPath, destPath);
               totalOverwritten++;
+              allManifest[mPath] = incomingHash;
             } else {
               totalSkipped++;
+              // Keep: the user claimed this file → project-owned → omit from
+              // the manifest so it is never mistaken for upstream content.
+              recordSkip(allManifest, mPath);
             }
-            allManifest[mPath] = incomingHash;
           }
         } else {
           if (!flags.dryRun) fs.copyFileSync(srcPath, destPath);
@@ -1382,6 +1416,27 @@ async function run() {
     }
   }
 
+  // --- Refresh the GLOBAL watchtower runtime (content-aware) ---
+  // The watchtower module copies its files into the PROJECT, but the global
+  // runtime at ~/.claude-cabinet/watchtower/ is set up only by the one-time
+  // `/watchtower install` SKILL.md step. Without this, a reinstall left the
+  // global runtime scripts/docs/hooks stale and never delivered newly shipped
+  // ones. refreshWatchtowerRuntime is REFRESH-ONLY: it no-ops (status
+  // 'absent', zero writes) when no runtime exists yet, so it's safe to call
+  // unconditionally whenever the module is selected.
+  if (selectedModules.includes('watchtower')) {
+    try {
+      const result = refreshWatchtowerRuntime({ dryRun: !!flags.dryRun });
+      if (result.status !== 'absent') {
+        console.log('');
+        for (const r of result.results || []) console.log(`  📋 ${r}`);
+      }
+    } catch (err) {
+      console.log(`  ⚠ watchtower runtime refresh failed: ${err.message}`);
+      console.log('    Re-run the installer to retry.');
+    }
+  }
+
   // --- Manifest key migration (act:d1f16bee) ---
   // When CC renames directories (e.g., perspectives/ → cabinet-*/), old manifest
   // keys no longer match new template paths. Migrate keys BEFORE cleanup so the
@@ -1610,6 +1665,18 @@ async function run() {
         // Register with folder name. /onboard fills in name and description later.
         registry.projects.push(entry);
       }
+      // --- Frontier-model designation (visibility watchdog) ---
+      // User-level, per-operator key. Read-preserve-rewrite: only the
+      // frontierModel key is touched; every other key rides through.
+      if (flags.frontierModelEmpty) {
+        console.log('  ⚠ Ignoring empty --frontier-model value (an empty key would match every model and silence the watchdog)');
+      }
+      if (flags.frontierModel) {
+        registry.frontierModel = flags.frontierModel;
+      } else if (typeof registry.frontierModel === 'string' && !registry.frontierModel.trim()) {
+        // Heal a hand-edited empty key — treat as absent (see parseArgs note).
+        delete registry.frontierModel;
+      }
       fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
       const otherCount = registry.projects.filter(p => p.path !== projectDir).length;
       if (otherCount > 0) {
@@ -1617,6 +1684,10 @@ async function run() {
       } else {
         console.log('  📋 Registered in project registry');
       }
+      // Self-announcing: print the effective designation on every run.
+      if (registry.frontierModel) {
+        console.log(`  🛰  Frontier model: ${registry.frontierModel} (visibility watchdog — /orient + SessionStart warn on mismatch; nothing is pinned)`);
+      }
     } catch (err) {
       // Non-fatal — registry is nice-to-have
     }

package/lib/copy.js

@@ -7,6 +7,49 @@ function hashContent(content) {
   return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
 }
 
+/**
+ * Record the manifest consequence of SKIPPING a file at install time
+ * (act:bf21c95b). The single shared rule for ALL skip sites in BOTH
+ * install code paths (lib/copy.js and the single-file branches in
+ * lib/cli.js):
+ *
+ *   - A skipped file whose on-disk content differs from the incoming
+ *     template is NOT upstream content — it is project-owned
+ *     (project-created, user-kept, or a customized phase). It must be
+ *     OMITTED from the manifest entirely. An absent entry means "not
+ *     ours". Recording any hash for it poisons the manifest: ownership
+ *     classification is manifest-PRESENCE-based, so the next install
+ *     would classify the file upstream-owned and silently overwrite it
+ *     (and cc-upstream-guard / cc-drift-check would false-positive on it).
+ *   - The one exception: a skipped file byte-identical to the incoming
+ *     template is indistinguishable from upstream content and stays
+ *     tracked under the template hash.
+ *
+ * Omission only — never a marker value or an alternate manifest value
+ * shape (lesson_shared_json_shape_drift). All manifest consumers
+ * (ownership classification, cleanup loop, key migration, cc-drift-check,
+ * cc-upstream-guard, lib/reset.js) treat an absent key as "not ours" and
+ * leave the file alone.
+ *
+ * Known limitation (documented, not solved here): manifests already
+ * poisoned by past installs cannot retroactively distinguish a recorded
+ * project-created file from genuine upstream content. This helper only
+ * prevents NEW poisoning.
+ *
+ * @param {object} manifest      manifest object being built for this install
+ * @param {string} key           manifest key for the skipped file
+ * @param {object} [opts]
+ * @param {boolean} [opts.identical]    on-disk content === incoming template
+ * @param {string}  [opts.incomingHash] hash of the incoming template content
+ */
+function recordSkip(manifest, key, { identical = false, incomingHash = null } = {}) {
+  if (identical && incomingHash) {
+    manifest[key] = incomingHash;
+  } else {
+    delete manifest[key];
+  }
+}
+
 /**
  * Recursively copy files from src to dest, surfacing conflicts.
  * Returns { copied: string[], skipped: string[], overwritten: string[] }
@@ -55,7 +98,8 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
             const trimmedExisting = existing.trim();
             if (trimmedExisting !== '' && trimmedExisting !== incoming.trim()) {
               results.skipped.push(relPath);
-              results.manifest[relPath] = hashContent(existing);
+              // Customized phase = project-owned content → omit from manifest.
+              recordSkip(results.manifest, relPath);
               console.log(`  Preserved customized phase: ${displayPath}`);
               continue;
             }
@@ -64,7 +108,7 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
 
         if (existing === incoming) {
           results.skipped.push(relPath);
-          results.manifest[relPath] = incomingHash;
+          recordSkip(results.manifest, relPath, { identical: true, incomingHash });
           continue;
         }
 
@@ -82,9 +126,8 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
             console.log(`  Updated: ${displayPath}`);
           } else {
             results.skipped.push(relPath);
-            // Record the hash of what's actually on disk, not the template —
-            // otherwise the manifest lies about file content after a skip.
-            results.manifest[relPath] = hashContent(existing);
+            // Project-created file → omit from manifest ("not ours").
+            recordSkip(results.manifest, relPath);
           }
           continue;
         }
@@ -101,9 +144,9 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
         });
 
         if (!response.action) {
-          // User cancelled
+          // User cancelled → file kept as-is → project-owned → omit.
           results.skipped.push(relPath);
-          results.manifest[relPath] = incomingHash;
+          recordSkip(results.manifest, relPath);
           continue;
         }
 
@@ -118,17 +161,20 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
           if (followUp.overwrite && !dryRun) {
             fs.copyFileSync(srcPath, destPath);
             results.overwritten.push(relPath);
+            results.manifest[relPath] = incomingHash;
           } else {
+            // Diff shown, user kept their file → project-owned → omit.
             results.skipped.push(relPath);
+            recordSkip(results.manifest, relPath);
           }
-          results.manifest[relPath] = incomingHash;
         } else if (response.action === 'overwrite') {
           if (!dryRun) fs.copyFileSync(srcPath, destPath);
           results.overwritten.push(relPath);
           results.manifest[relPath] = incomingHash;
         } else {
+          // 'Keep existing' → project-owned → omit from manifest.
           results.skipped.push(relPath);
-          results.manifest[relPath] = incomingHash;
+          recordSkip(results.manifest, relPath);
         }
       } else {
         if (!dryRun) {
@@ -169,4 +215,4 @@ function showDiff(existing, incoming, relPath) {
   console.log('');
 }
 
-module.exports = { copyTemplates };
+module.exports = { copyTemplates, recordSkip };

package/lib/engagement-server-setup.js

@@ -9,7 +9,10 @@
  *
  * Version semantics:
  *   - First install: copy all managed files, create data dir, write .cc-version
- *   - Same version: skip with log
+ *   - Same version: fall through to the SHA256 manifest hash-compare and
+ *     copy only files whose hashes differ (dogfood-from-source changes
+ *     templates without a version bump — equal-version must still
+ *     propagate; the manifest check makes this cheap and idempotent)
  *   - Newer CC version: upgrade managed files, preserve data dir
  *   - Older CC version than installed: skip (don't downgrade)
  */
@@ -23,6 +26,7 @@ const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
 const GLOBAL_MANIFEST_PATH = path.join(CC_HOME, 'global-manifest.json');
 const INSTALL_DIR = path.join(CC_HOME, 'engagement-server');
 const VERSION_FILE = path.join(INSTALL_DIR, '.cc-version');
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'templates', 'engagement-server');
 
 const MANAGED_FILES = [
   'server.mjs',
@@ -99,7 +103,7 @@ function setupEngagementServer(opts = {}) {
   const results = [];
 
   const ccVersion = require('../package.json').version;
-  const templateDir = path.resolve(__dirname, '..', 'templates', 'engagement-server');
+  const templateDir = TEMPLATE_DIR;
 
   if (!fs.existsSync(templateDir)) {
     throw new Error(`engagement-server-setup: ${templateDir} not found.`);
@@ -109,15 +113,19 @@ function setupEngagementServer(opts = {}) {
 
   if (installedVersion) {
     const cmp = compareVersions(ccVersion, installedVersion);
-    if (cmp === 0) {
-      results.push(`engagement-server ${installedVersion} already installed — skipping`);
-      return { results, status: 'skipped' };
-    }
     if (cmp < 0) {
       results.push(`engagement-server ${installedVersion} is newer than CC ${ccVersion} — skipping (won't downgrade)`);
       return { results, status: 'skipped' };
     }
-    results.push(`Upgrading engagement-server from ${installedVersion} to ${ccVersion}`);
+    // Equal version (cmp === 0): do NOT early-return. Fall through to the
+    // SHA256 manifest hash-compare below — it copies only changed files,
+    // so a dogfood-from-source template edit propagates even without a
+    // package.json version bump. The hash-compare makes this idempotent.
+    if (cmp === 0) {
+      results.push(`engagement-server ${installedVersion} already installed — checking for changed files`);
+    } else {
+      results.push(`Upgrading engagement-server from ${installedVersion} to ${ccVersion}`);
+    }
   } else {
     results.push(`Installing engagement-server ${ccVersion}`);
   }
@@ -187,7 +195,24 @@ function setupEngagementServer(opts = {}) {
     results.push(`  Re-deploy: cd ${INSTALL_DIR} && railway up --detach`);
   }
 
-  return { results, status: installedVersion ? 'upgraded' : 'installed' };
+  let status;
+  if (!installedVersion) {
+    status = 'installed';
+  } else if (copiedCount > 0) {
+    status = 'upgraded';
+  } else {
+    // Equal-or-newer version, manifest already current — nothing to do.
+    status = 'unchanged';
+  }
+  return { results, status };
 }
 
-module.exports = { setupEngagementServer };
+// MANAGED_FILES, INSTALL_DIR, and TEMPLATE_DIR are exported for the
+// version-gate test so it can seed a faithful, complete global manifest
+// (single source of truth — the test never re-derives the file list).
+module.exports = {
+  setupEngagementServer,
+  MANAGED_FILES,
+  INSTALL_DIR,
+  TEMPLATE_DIR,
+};

package/lib/migrate-from-omega.js

@@ -82,6 +82,13 @@ function stripUserPrefix(raw, homeDir) {
     const segs = tail.split('/');
     return segs.slice(1).join('/');
   }
+  // Omega project keys are historical strings recorded on whatever machine
+  // wrote them — a DB carried from a Mac to a Linux box (or exercised on a
+  // Linux CI runner) still holds /Users/<name>/... paths that the current
+  // machine's home root won't match. Recognize the conventional home roots
+  // structurally so cross-machine migrations classify instead of crashing.
+  const foreignHome = raw.match(/^\/(?:Users|home)\/[^/]+\/(.+)$/);
+  if (foreignHome) return foreignHome[1];
   return raw;
 }
 
@@ -100,7 +107,12 @@ function canonicalizeProjectKey(raw, ctx = {}) {
   const slugPath = stripUserPrefix(work, ctx.homeDir);
   const topSlug = slugPath.split('/')[0];
 
-  return { canonical: topSlug || null, kind: 'project' };
+  // kind 'project' with a null canonical is an incoherent contract — the
+  // bucketing consumer would key a cross-project map on null and crash on
+  // slug derivation. An unclassifiable key is unscoped, not a null project.
+  if (!topSlug) return { canonical: null, kind: 'unscoped' };
+
+  return { canonical: topSlug, kind: 'project' };
 }
 
 function resolveCurrentProject(cwd, homeDir) {

package/lib/mux-setup.js

@@ -8,7 +8,10 @@
  *
  * Version semantics:
  *   - First install: copy all managed files, write .cc-version
- *   - Same version: skip with log
+ *   - Same version: fall through to the SHA256 manifest hash-compare and
+ *     copy only files whose hashes differ (dogfood-from-source changes
+ *     templates without a version bump — equal-version must still
+ *     propagate; the manifest check makes this cheap and idempotent)
  *   - Newer CC version: upgrade managed files, preserve data dirs
  *   - Older CC version than installed: skip (don't downgrade)
  */
@@ -21,6 +24,7 @@ const crypto = require('crypto');
 const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
 const GLOBAL_MANIFEST_PATH = path.join(CC_HOME, 'global-manifest.json');
 const MUX_VERSION_FILE = path.join(os.homedir(), '.config', 'mux', '.cc-version');
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'templates', 'mux');
 
 const MANAGED_FILES = [
   { src: 'bin/mux', dest: path.join(os.homedir(), '.local', 'bin', 'mux'), mode: 0o755 },
@@ -45,6 +49,7 @@ const MANAGED_FILES = [
   { src: 'config/worktree-session-health.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-session-health.sh'), mode: 0o755 },
   { src: 'config/worktree-health-popup.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-health-popup.sh'), mode: 0o755 },
   { src: 'config/worktree-cleanup.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-cleanup.sh'), mode: 0o755 },
+  { src: 'config/worktree-dirty-check.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-dirty-check.sh'), mode: 0o755 },
   { src: 'config/mux.tmux.conf', dest: path.join(os.homedir(), '.config', 'mux', 'mux.tmux.conf') },
   { src: 'config/unwrap-copy.py', dest: path.join(os.homedir(), '.config', 'mux', 'unwrap-copy.py'), mode: 0o755 },
   { src: 'config/screenshot-to-clipboard.sh', dest: path.join(os.homedir(), '.config', 'mux', 'screenshot-to-clipboard.sh'), mode: 0o755 },
@@ -121,7 +126,7 @@ function setupMux(opts = {}) {
   const results = [];
 
   const ccVersion = require('../package.json').version;
-  const templateDir = path.resolve(__dirname, '..', 'templates', 'mux');
+  const templateDir = TEMPLATE_DIR;
 
   if (!fs.existsSync(templateDir)) {
     throw new Error(`mux-setup: ${templateDir} not found.`);
@@ -131,15 +136,19 @@ function setupMux(opts = {}) {
 
   if (installedVersion) {
     const cmp = compareVersions(ccVersion, installedVersion);
-    if (cmp === 0) {
-      results.push(`mux ${installedVersion} already installed — skipping`);
-      return { results, status: 'skipped' };
-    }
     if (cmp < 0) {
       results.push(`mux ${installedVersion} is newer than CC ${ccVersion} — skipping (won't downgrade)`);
       return { results, status: 'skipped' };
     }
-    results.push(`Upgrading mux from ${installedVersion} to ${ccVersion}`);
+    // Equal version (cmp === 0): do NOT early-return. Fall through to the
+    // SHA256 manifest hash-compare below — it copies only changed files,
+    // so a dogfood-from-source template edit propagates even without a
+    // package.json version bump. The hash-compare makes this idempotent.
+    if (cmp === 0) {
+      results.push(`mux ${installedVersion} already installed — checking for changed files`);
+    } else {
+      results.push(`Upgrading mux from ${installedVersion} to ${ccVersion}`);
+    }
   } else {
     results.push(`Installing mux ${ccVersion}`);
   }
@@ -199,7 +208,16 @@ function setupMux(opts = {}) {
     setupDarwinIntegration({ dryRun, results });
   }
 
-  return { results, status: installedVersion ? 'upgraded' : 'installed' };
+  let status;
+  if (!installedVersion) {
+    status = 'installed';
+  } else if (copiedCount > 0) {
+    status = 'upgraded';
+  } else {
+    // Equal-or-newer version, manifest already current — nothing to do.
+    status = 'unchanged';
+  }
+  return { results, status };
 }
 
 /**
@@ -307,4 +325,11 @@ function setupDarwinIntegration({ dryRun, results }) {
   }
 }
 
-module.exports = { setupMux };
+// MANAGED_FILES and TEMPLATE_DIR are exported for the version-gate test so it
+// can seed a faithful, complete global manifest (single source of truth — the
+// test never re-derives the file list).
+module.exports = {
+  setupMux,
+  MANAGED_FILES,
+  TEMPLATE_DIR,
+};