create-claude-cabinet 0.39.0 → 0.40.0

package/README.md

@@ -221,6 +221,17 @@ the listed modules to what's already there, it doesn't replace your
 module set. Safe to run on a mature project without losing
 customization. You can pass multiple modules: `--modules verify,audit`.
 
+### Opt-in Modules
+
+| Module | What it does |
+|--------|-------------|
+| **verify** | Cucumber + Playwright walkthrough verification harness |
+| **site-audit** | 14-check deployed-site quality audit with HTML reports |
+| **engagement** | Client engagement management — packets, billing, feedback loops |
+| **engagement-server** | Central multi-engagement API server (Railway/Fly deploy) |
+| **watchtower** | Continuous background state management replacing orient/debrief |
+| **mux** | Multi-project terminal manager — desks, auto-worktrees with shared identity, trail logging, DX captures, portal color-switching |
+
 ## CLI Options
 
 ```

package/lib/cli.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const os = require('os');
 const crypto = require('crypto');
 const { copyTemplates } = require('./copy');
-const { mergeSettings, healUserSettings, mergeWatchtowerHooks } = require('./settings-merge');
+const { mergeSettings, healUserSettings, mergeWatchtowerHooks, mergeMuxHooks } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupVerifyRuntime } = require('./verify-setup');
@@ -496,7 +496,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: false,
-    templates: ['rules/enforcement-pipeline.md', 'memory/patterns/_pattern-template.md', 'memory/patterns/pattern-intelligence-first.md'],
+    templates: ['rules/enforcement-pipeline.md', 'rules/maintainability.md', 'memory/patterns/_pattern-template.md', 'memory/patterns/pattern-intelligence-first.md'],
   },
   'memory': {
     name: 'Built-In Memory (cc-remember + reader + validator)',
@@ -623,7 +623,7 @@ const MODULES = {
   },
   watchtower: {
     name: 'Watchtower (continuous background state)',
-    description: 'Replaces orient/debrief with continuous background processing. Three rings (mechanical cron, Claude intelligence, session-aware), ambient state injection via SessionStart hook, and an asynchronous decision queue. Sessions start informed with minimal context cost.',
+    description: 'Replaces orient/debrief with continuous background processing. Three rings (mechanical cron, Claude intelligence, session-aware), ambient state injection via SessionStart hook, and an inbox for extracted knowledge and signals. Sessions start informed with minimal context cost.',
     mandatory: false,
     default: false,
     lean: false,
@@ -632,6 +632,7 @@ const MODULES = {
       'cabinet/watchtower-contracts.md',
       'scripts/watchtower-lib.mjs',
       'scripts/watchtower-queue.mjs',
+      'skills/inbox',
       'skills/decisions',
       'hooks/watchtower-session-start.sh',
       'scripts/watchtower-build-context.mjs',
@@ -651,6 +652,7 @@ const MODULES = {
       'watchtower/watchtower-ring2-slow.timer',
       'hooks/watchtower-session-end.sh',
       'scripts/watchtower-ring3-close.mjs',
+      'scripts/watchtower-status.sh',
       'skills/briefing',
     ],
   },
@@ -1285,6 +1287,11 @@ async function run() {
       mergeWatchtowerHooks(settingsPath);
       console.log('  ⚙️  Registered watchtower SessionStart/SessionEnd hooks');
     }
+
+    if (selectedModules.includes('mux')) {
+      mergeMuxHooks(settingsPath);
+      console.log('  ⚙️  Registered mux worktree health SessionStart hook');
+    }
   }
 
   // --- Heal user-level ~/.claude/settings.json ---

package/lib/mux-setup.js

@@ -42,6 +42,9 @@ const MANAGED_FILES = [
   { src: 'config/help.txt', dest: path.join(os.homedir(), '.config', 'mux', 'help.txt') },
   { src: 'config/_mux', dest: path.join(os.homedir(), '.config', 'mux', '_mux') },
   { src: 'config/mux.bash', dest: path.join(os.homedir(), '.config', 'mux', 'mux.bash') },
+  { 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 },
 ];
 
 const DATA_DIRS = [
@@ -50,6 +53,7 @@ const DATA_DIRS = [
   path.join(os.homedir(), '.config', 'mux', 'notes'),
   path.join(os.homedir(), '.config', 'mux', 'dx'),
   path.join(os.homedir(), '.config', 'mux', 'pending-prompts'),
+  path.join(os.homedir(), '.local', 'share', 'mux', 'wt-health'),
 ];
 
 function sha256(content) {

package/lib/settings-merge.js

@@ -107,6 +107,20 @@ const WATCHTOWER_HOOKS = {
   ],
 };
 
+const MUX_HOOKS = {
+  SessionStart: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: '$HOME/.config/mux/worktree-session-health.sh',
+        },
+      ],
+    },
+  ],
+};
+
 // Legacy hook script names that should be stripped on any merge.
 // Centralizes cleanup so a user who skips --migrate-memory but runs
 // any other CC operation still gets omega-era hooks pruned.
@@ -264,4 +278,29 @@ function mergeWatchtowerHooks(settingsPath) {
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
-module.exports = { mergeSettings, healUserSettings, mergeWatchtowerHooks, DEFAULT_HOOKS, WATCHTOWER_HOOKS, LEGACY_HOOK_COMMANDS };
+function mergeMuxHooks(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return;
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  if (!settings.hooks) settings.hooks = {};
+
+  for (const [event, newHooks] of Object.entries(MUX_HOOKS)) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = newHooks;
+    } else {
+      for (const newHook of newHooks) {
+        const hookKey = h => h.command || h.prompt || '';
+        const existingKeys = settings.hooks[event].flatMap(h =>
+          h.hooks.map(hh => hookKey(hh))
+        );
+        const newKeys = newHook.hooks.map(h => hookKey(h));
+        if (!newKeys.every(k => existingKeys.includes(k))) {
+          settings.hooks[event].push(newHook);
+        }
+      }
+    }
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+module.exports = { mergeSettings, healUserSettings, mergeWatchtowerHooks, mergeMuxHooks, DEFAULT_HOOKS, WATCHTOWER_HOOKS, MUX_HOOKS, LEGACY_HOOK_COMMANDS };

package/package.json

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

package/templates/cabinet/_cabinet-member-template.md

@@ -125,33 +125,19 @@ to anchor the boundaries.
 
 ### 7. Historically Problematic Patterns
 
-Two-file overlay:
-
 ```markdown
 ## Historically Problematic Patterns
 
-Two sources — read both and merge at runtime:
-
-1. **This section** (upstream, CC-owned) — universal patterns that apply to
-   any project. Grows when consuming projects promote recurring findings
-   via field-feedback.
-2. **`patterns-project.md`** in this skill's directory — project-specific
-   patterns discovered during audits of this particular project. Project-
-   owned, never overwritten by CC upgrades.
-
-If `patterns-project.md` exists, read it alongside this section. Both
-inform your analysis equally.
-
-**How patterns get here:** A consuming project's audit finds a real issue.
-If the same pattern recurs across projects, it gets promoted upstream via
-field-feedback. The CC maintainer adds it to this section. Project-specific
-patterns that don't generalize stay in `patterns-project.md`.
+Read `patterns-project.md` in this skill directory for project-specific
+patterns from prior audits. Apply alongside universal patterns below.
 
 <!-- Universal patterns below this line -->
 ```
 
-This section starts empty for new members. It accumulates from real
-findings over time — never pre-fill with hypothetical patterns.
+This section starts empty for new members. Universal patterns accumulate
+from real field-feedback findings over time — never pre-fill with
+hypothetical patterns. Project-specific patterns live in
+`patterns-project.md` (project-owned, never overwritten by CC upgrades).
 
 ## Optional Sections
 

package/templates/cabinet/watchtower-contracts.md

@@ -17,12 +17,12 @@ fs.renameSync(tmp, filePath);
 
 ## No-Index Convention
 
-The decision queue uses directory listing, not an index file. To list
+The inbox queue uses directory listing, not an index file. To list
 pending items, read `queue/items/`, open each `.json`, filter by
 status. No manifest, no index.json.
 
 Rationale: one fewer file to keep consistent. Directory listing is
-O(n) but n is small (decision queues rarely exceed 50 items). If
+O(n) but n is small (inbox items rarely exceed 50 items). If
 listing exceeds 2 seconds or 500 items, revisit via `act:2b638b02`.
 
 ## Schema Versioning
@@ -70,7 +70,7 @@ standard files:
 | `memory-refs.md` | Ring 2 fast | Relevant memory entries |
 | `options-analysis.md` | Ring 2 fast | Pros/cons with evidence |
 
-`/decisions` reads these when `enrichment_status` is `"complete"`.
+`/inbox` reads these when `enrichment_status` is `"complete"`.
 Missing files degrade gracefully (null in the read result).
 
 ## Deferred Schemas
@@ -85,3 +85,75 @@ their owning plan ships:
 | `hooks/<ring>-<phase>.d/` | Plan 9 | Lifecycle hooks |
 | `logs/<ring>.log` | Plan 4 | Ring 1 runner |
 | `lock/<ring>.pid` | Plan 4 | Ring 1 runner |
+
+## Ring 4 — Periodic Truth Reconciliation (design phase)
+
+**Status: concept. Needs design session before implementation.**
+
+Rings 1–3 operate on individual signals: individual files (R1),
+individual patterns (R2), individual sessions (R3). Nothing catches
+**cumulative drift** — the slow rot where twenty sessions each move
+reality a little further from what documents claim, but no single
+session is the tipping point.
+
+Ring 4 is the answer to: "Is what we wrote still true?"
+
+### The problem it solves
+
+The maginnis project's architecture briefing said "Layer 4 Not built"
+and "tech stack TBD" for three weeks after the platform shipped with
+a Rails 8 app, Mantine frontend, 421 RSpec specs, and staging on
+Railway. No individual session caused the staleness. No individual
+session's debrief would flag it. The drift was invisible until
+someone tried to use the briefing for a real audit and found it
+described a project that no longer existed.
+
+This class of problem includes:
+- **Briefing-to-codebase drift** — claims about architecture, tech
+  stack, file layout, or project state that no longer match reality
+- **Memory-to-codebase drift** — memory files that reference
+  functions, files, or flags that have been renamed or removed
+- **CLAUDE.md drift** — sections describing architecture or
+  conventions that have been refactored past
+- **Plan-to-reality drift** — plan files describing work that's been
+  done but never marked complete, or describing approaches that were
+  abandoned
+
+### Cadence and weight
+
+Less frequent than R1–R3. Daily or weekly, not per-session or
+per-minute. Heavier per run — reads real code, cross-references
+document claims against codebase state, may invoke Claude for
+semantic comparison. Acceptable cost because it runs rarely and
+catches problems that compound silently.
+
+### Relationship to other rings
+
+Following the nervous system principle (not a stack): R4 consumes
+signals from R1–R3 (what changed recently, what sessions touched,
+what patterns emerged) to prioritize what to reconcile. R4 produces
+inbox items when drift is detected. R4 does not mutate documents —
+it flags, the user triages and routes.
+
+R3 catches "this session broke the briefing." R4 catches "the
+briefing has been slowly wrong for three weeks and nobody noticed."
+They're complementary, not redundant.
+
+### Open design questions
+
+- **Scope per run:** Reconcile everything every time, or rotate
+  through documents on a schedule? Full sweep is thorough but
+  expensive; rotation risks missing urgent drift on off-cycle docs.
+- **Drift threshold:** How wrong does a document need to be before
+  it's worth flagging? A missing model in the architecture briefing
+  is clear; a slightly outdated line count is noise.
+- **Trigger vs schedule:** Pure schedule (weekly), or also triggered
+  when R1/R2 detect significant codebase changes (new migration,
+  major refactor, new dependency)?
+- **Cross-project scope:** Per-project reconciliation, or also
+  cross-project (e.g., a CC template claiming something about
+  consumer behavior that's no longer true)?
+- **Relationship to Ring 2 slow tier:** R2 slow already does some
+  staleness detection (stale work, memory hygiene). Where's the line
+  between R2's "is this work item stale?" and R4's "is this document
+  still true?" Is R4 an extension of R2 slow, or genuinely distinct?

package/templates/engagement-server/Dockerfile

@@ -1,5 +1,7 @@
 FROM node:20-slim
 
+RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 
 COPY package.json package-lock.json* ./

package/templates/engagement-server/server.mjs

@@ -73,7 +73,7 @@ function hashToken(raw) {
   return createHash('sha256').update(raw).digest('hex');
 }
 
-function resolveToken(tokenHash) {
+function resolveLocalToken(tokenHash) {
   return db.prepare(`
     SELECT u.id AS user_id, u.engagement_id, u.role, u.name AS user_name,
            e.auth_mode, e.auth_config
@@ -84,31 +84,83 @@ function resolveToken(tokenHash) {
   `).get(tokenHash);
 }
 
+function getExternalEngagements() {
+  return db.prepare(`
+    SELECT id, auth_config FROM engagements
+    WHERE auth_mode = 'external' AND auth_config IS NOT NULL
+  `).all();
+}
+
+function resolveExternalUser(engagementId, email, roleMapping) {
+  const user = db.prepare(`
+    SELECT id AS user_id, engagement_id, role, name AS user_name
+    FROM users
+    WHERE engagement_id = ? AND email = ?
+  `).get(engagementId, email);
+  if (user) return user;
+
+  return null;
+}
+
 async function authenticateRequest(req) {
   const authHeader = req.headers['authorization'];
   if (!authHeader || !authHeader.startsWith('Bearer ')) return null;
 
   const raw = authHeader.slice(7);
-  const tokenData = resolveToken(hashToken(raw));
-  if (!tokenData) return null;
 
-  if (tokenData.auth_mode === 'external' && tokenData.auth_config) {
+  // Path 1: local token lookup (works for all auth modes)
+  const localData = resolveLocalToken(hashToken(raw));
+  if (localData && localData.auth_mode === 'local') return localData;
+
+  // Path 2: external auth — forward token to client app's validate_url
+  const externals = getExternalEngagements();
+  for (const eng of externals) {
     try {
-      const config = JSON.parse(tokenData.auth_config);
-      if (config.validate_url) {
-        const resp = await fetch(config.validate_url, {
-          headers: { 'Authorization': `Bearer ${raw}` },
-          signal: AbortSignal.timeout(5000),
-        });
-        if (!resp.ok) return null;
-      }
+      const config = JSON.parse(eng.auth_config);
+      if (!config.validate_url) continue;
+
+      const resp = await fetch(config.validate_url, {
+        headers: { 'Authorization': `Bearer ${raw}` },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!resp.ok) continue;
+
+      const identity = await resp.json();
+      const email = identity.email;
+      if (!email) continue;
+
+      // Map platform role to engagement role via role_mapping
+      const roleMapping = config.role_mapping || {};
+      const mappedRole = roleMapping[identity.role] || identity.role;
+
+      // Find matching local user by email for message attribution
+      const user = resolveExternalUser(eng.id, email, roleMapping);
+      if (user) return { ...user, auth_mode: 'external' };
+
+      // User authenticated with platform but no local user record —
+      // auto-create so messages are properly attributed
+      const userId = `usr_${randomBytes(6).toString('hex')}`;
+      const engRole = ['consultant', 'client'].includes(mappedRole) ? mappedRole : 'client';
+      db.prepare(`INSERT INTO users (id, engagement_id, name, email, role) VALUES (?, ?, ?, ?, ?)`)
+        .run(userId, eng.id, email.split('@')[0], email, engRole);
+
+      return {
+        user_id: userId,
+        engagement_id: eng.id,
+        role: engRole,
+        user_name: email.split('@')[0],
+        auth_mode: 'external',
+      };
     } catch (err) {
-      console.error(`External auth failed: ${err.message}`);
-      return { error: 'auth_backend_unavailable' };
+      console.error(`External auth failed for engagement ${eng.id}: ${err.message}`);
     }
   }
 
-  return tokenData;
+  // Path 3: local token in an external-auth engagement (consultant-side
+  // tokens may still be locally managed)
+  if (localData) return localData;
+
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -278,18 +330,18 @@ const server = createServer(async (req, res) => {
   const path = url.pathname;
   const method = req.method;
 
+  // Health check — no auth, before HTTPS enforcement (Railway internal probes lack x-forwarded-proto)
+  if (path === '/health' && method === 'GET') {
+    logRequest(req, 200, null);
+    return json(res, 200, { ok: true, version: SCHEMA_VERSION });
+  }
+
   // HTTPS enforcement (Railway terminates TLS)
   if (process.env.RAILWAY_ENVIRONMENT && req.headers['x-forwarded-proto'] !== 'https') {
     logRequest(req, 421, null);
     return json(res, 421, { error: 'https_required' });
   }
 
-  // Health check — no auth
-  if (path === '/health' && method === 'GET') {
-    logRequest(req, 200, null);
-    return json(res, 200, { ok: true, version: SCHEMA_VERSION });
-  }
-
   // All other routes require auth
   const authHeader = req.headers['authorization'];
   if (!authHeader || !authHeader.startsWith('Bearer ')) {