create-claude-cabinet 0.38.0 → 0.39.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, 31 domain experts, a planning process, and the
+gives Claude a memory, 32 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** — 31 domain experts (security, accessibility,
+- **Cabinet members** — 32 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)
 
-31 expert cabinet members who each own a domain and stay in their lane.
+32 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
@@ -240,7 +240,7 @@ source code.
 ```
 .claude/
 ├── skills/          # orient, debrief, plan, execute, audit, etc.
-│   └── cabinet-*/   # 31 cabinet member definitions
+│   └── cabinet-*/   # 32 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

@@ -4,12 +4,14 @@ const fs = require('fs');
 const os = require('os');
 const crypto = require('crypto');
 const { copyTemplates } = require('./copy');
-const { mergeSettings, healUserSettings } = require('./settings-merge');
+const { mergeSettings, healUserSettings, mergeWatchtowerHooks } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupVerifyRuntime } = require('./verify-setup');
 const { setupSiteAuditRuntime } = require('./site-audit-setup');
 const { setupEngagement } = require('./engagement-setup');
+const { setupMux } = require('./mux-setup');
+const { setupEngagementServer } = require('./engagement-server-setup');
 const { reset } = require('./reset');
 
 const VERSION = require('../package.json').version;
@@ -543,6 +545,7 @@ const MODULES = {
       'skills/cabinet-ui-experimentalist', 'skills/cabinet-user-advocate',
       'skills/cabinet-vision',
       'skills/cabinet-narrative-architect', 'skills/cabinet-interactive-storyteller',
+      'skills/cabinet-elegance',
       'scripts/merge-findings.js', 'scripts/load-triage-history.js',
       'scripts/triage-server.mjs', 'scripts/triage-ui.html',
       'scripts/finding-schema.json', 'scripts/resolve-committees.cjs',
@@ -618,6 +621,58 @@ const MODULES = {
       'engagement',
     ],
   },
+  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.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    templates: [
+      'scripts/watchtower-validate.mjs',
+      'cabinet/watchtower-contracts.md',
+      'scripts/watchtower-lib.mjs',
+      'scripts/watchtower-queue.mjs',
+      'skills/decisions',
+      'hooks/watchtower-session-start.sh',
+      'scripts/watchtower-build-context.mjs',
+      'scripts/watchtower-ring1.mjs',
+      'scripts/watchtower-ring1-runner.sh',
+      'skills/watchtower',
+      'watchtower/com.claude-cabinet.watchtower-ring1.plist',
+      'watchtower/watchtower-ring1.service',
+      'watchtower/watchtower-ring1.timer',
+      'scripts/watchtower-ring2.mjs',
+      'scripts/watchtower-ring2-runner.sh',
+      'watchtower/com.claude-cabinet.watchtower-ring2-fast.plist',
+      'watchtower/com.claude-cabinet.watchtower-ring2-slow.plist',
+      'watchtower/watchtower-ring2-fast.service',
+      'watchtower/watchtower-ring2-fast.timer',
+      'watchtower/watchtower-ring2-slow.service',
+      'watchtower/watchtower-ring2-slow.timer',
+      'hooks/watchtower-session-end.sh',
+      'scripts/watchtower-ring3-close.mjs',
+      'skills/briefing',
+    ],
+  },
+  mux: {
+    name: 'Mux (tmux project manager)',
+    description: 'Multi-project terminal manager. Desks (tmux sessions), auto-worktrees, trail logging, sticky notes, portal color-switching, and an MCP server for Claude. Installs to user-level paths (~/.local/bin/, ~/.config/mux/).',
+    mandatory: false,
+    default: false,
+    lean: false,
+    postInstall: 'mux-setup',
+    templates: ['skills/orient/phases/dx-captures.md'],
+  },
+  'engagement-server': {
+    name: 'Engagement Server',
+    description: 'Central multi-engagement API server. Deploys once to Railway/Fly, serves all client engagements. User-level infrastructure.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    requires: ['engagement', 'work-tracking'],
+    postInstall: 'engagement-server-setup',
+    templates: [],
+  },
 };
 
 /** Recursively collect all relative file paths under a directory. */
@@ -1225,6 +1280,11 @@ async function run() {
   if (selectedModules.includes('hooks') && !flags.dryRun) {
     const settingsPath = mergeSettings(projectDir, { includeDb });
     console.log(`  ⚙️  Merged hooks into ${path.relative(projectDir, settingsPath)}`);
+
+    if (selectedModules.includes('watchtower')) {
+      mergeWatchtowerHooks(settingsPath);
+      console.log('  ⚙️  Registered watchtower SessionStart/SessionEnd hooks');
+    }
   }
 
   // --- Heal user-level ~/.claude/settings.json ---
@@ -1276,6 +1336,8 @@ async function run() {
     'verify-setup': setupVerifyRuntime,
     'site-audit-setup': setupSiteAuditRuntime,
     'engagement-setup': setupEngagement,
+    'mux-setup': setupMux,
+    'engagement-server-setup': setupEngagementServer,
   };
   for (const moduleKey of selectedModules) {
     const mod = MODULES[moduleKey];

package/lib/engagement-server-setup.js

@@ -0,0 +1,189 @@
+/**
+ * engagement-server-setup.js — install engagement server to user-level paths.
+ *
+ * Follows the mux-setup.js pattern: user-level infrastructure managed by CC,
+ * tracked via global manifest at ~/.claude-cabinet/global-manifest.json.
+ *
+ * Installs to ~/.claude-cabinet/engagement-server/. The user deploys to
+ * Railway (or similar) separately.
+ *
+ * Version semantics:
+ *   - First install: copy all managed files, create data dir, write .cc-version
+ *   - Same version: skip with log
+ *   - Newer CC version: upgrade managed files, preserve data dir
+ *   - Older CC version than installed: skip (don't downgrade)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+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 INSTALL_DIR = path.join(CC_HOME, 'engagement-server');
+const VERSION_FILE = path.join(INSTALL_DIR, '.cc-version');
+
+const MANAGED_FILES = [
+  'server.mjs',
+  'engage-server.mjs',
+  'schema.sql',
+  'package.json',
+  'Dockerfile',
+  'railway.toml',
+];
+
+const DATA_DIRS = [
+  path.join(INSTALL_DIR, 'data'),
+  path.join(INSTALL_DIR, 'migrations'),
+];
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return 1;
+    if (va < vb) return -1;
+  }
+  return 0;
+}
+
+function readGlobalManifest() {
+  if (!fs.existsSync(GLOBAL_MANIFEST_PATH)) return { files: {} };
+  try {
+    return JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+  } catch {
+    return { files: {} };
+  }
+}
+
+function writeGlobalManifest(manifest) {
+  fs.mkdirSync(path.dirname(GLOBAL_MANIFEST_PATH), { recursive: true });
+  const tmp = GLOBAL_MANIFEST_PATH + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+  fs.renameSync(tmp, GLOBAL_MANIFEST_PATH);
+}
+
+function readInstalledVersion() {
+  if (!fs.existsSync(VERSION_FILE)) return null;
+  try {
+    return fs.readFileSync(VERSION_FILE, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeVersion(version) {
+  fs.mkdirSync(path.dirname(VERSION_FILE), { recursive: true });
+  fs.writeFileSync(VERSION_FILE, version + '\n');
+}
+
+/**
+ * @param {Object} opts
+ * @param {boolean} [opts.dryRun]
+ * @param {string} [opts.projectDir]
+ * @returns {{ results: string[], status: string }}
+ */
+function setupEngagementServer(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const results = [];
+
+  const ccVersion = require('../package.json').version;
+  const templateDir = path.resolve(__dirname, '..', 'templates', 'engagement-server');
+
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`engagement-server-setup: ${templateDir} not found.`);
+  }
+
+  const installedVersion = readInstalledVersion();
+
+  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}`);
+  } else {
+    results.push(`Installing engagement-server ${ccVersion}`);
+  }
+
+  // Create data directories (preserved across upgrades)
+  for (const dir of DATA_DIRS) {
+    if (!fs.existsSync(dir)) {
+      if (dryRun) {
+        results.push(`  [dry-run] mkdir -p ${dir}`);
+      } else {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  // Copy managed files
+  const manifest = readGlobalManifest();
+  let copiedCount = 0;
+
+  for (const file of MANAGED_FILES) {
+    const srcPath = path.join(templateDir, file);
+    const destPath = path.join(INSTALL_DIR, file);
+
+    if (!fs.existsSync(srcPath)) {
+      results.push(`  ⚠ Template missing: ${file}`);
+      continue;
+    }
+
+    const content = fs.readFileSync(srcPath);
+    const hash = sha256(content);
+
+    if (manifest.files[destPath] === hash) {
+      continue;
+    }
+
+    if (dryRun) {
+      results.push(`  [dry-run] ${file} → ${destPath}`);
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.writeFileSync(destPath, content);
+      manifest.files[destPath] = hash;
+    }
+    copiedCount++;
+  }
+
+  if (!dryRun) {
+    manifest.version = ccVersion;
+    manifest.installedAt = new Date().toISOString();
+    writeGlobalManifest(manifest);
+    writeVersion(ccVersion);
+  }
+
+  if (copiedCount > 0) {
+    results.push(`  Copied ${copiedCount} file(s) to ${INSTALL_DIR}`);
+  }
+
+  if (!installedVersion) {
+    results.push('');
+    results.push('  Next steps:');
+    results.push(`    cd ${INSTALL_DIR}`);
+    results.push('    npm install');
+    results.push('    railway init   # or railway link');
+    results.push('    railway volume add -m /app/data');
+    results.push('    railway up --detach');
+  } else {
+    results.push('');
+    results.push(`  Re-deploy: cd ${INSTALL_DIR} && railway up --detach`);
+  }
+
+  return { results, status: installedVersion ? 'upgraded' : 'installed' };
+}
+
+module.exports = { setupEngagementServer };

package/lib/mux-setup.js

@@ -0,0 +1,189 @@
+/**
+ * mux-setup.js — install mux files to user-level paths.
+ *
+ * First user-level module in CC. Unlike project-scoped templates that
+ * copy to .claude/ and scripts/, mux installs to ~/.local/bin/,
+ * ~/.config/mux/, and ~/.local/share/mux/. Tracked via a global
+ * manifest at ~/.claude-cabinet/global-manifest.json.
+ *
+ * Version semantics:
+ *   - First install: copy all managed files, write .cc-version
+ *   - Same version: skip with log
+ *   - Newer CC version: upgrade managed files, preserve data dirs
+ *   - Older CC version than installed: skip (don't downgrade)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+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 MANAGED_FILES = [
+  { src: 'bin/mux', dest: path.join(os.homedir(), '.local', 'bin', 'mux'), mode: 0o755 },
+  { src: 'config/muxlib.py', dest: path.join(os.homedir(), '.config', 'mux', 'muxlib.py') },
+  { src: 'config/trail-add.sh', dest: path.join(os.homedir(), '.config', 'mux', 'trail-add.sh'), mode: 0o755 },
+  { src: 'config/status-set.sh', dest: path.join(os.homedir(), '.config', 'mux', 'status-set.sh'), mode: 0o755 },
+  { src: 'config/trail-popup.py', dest: path.join(os.homedir(), '.config', 'mux', 'trail-popup.py') },
+  { src: 'config/status-popup.py', dest: path.join(os.homedir(), '.config', 'mux', 'status-popup.py') },
+  { src: 'config/dashboard.py', dest: path.join(os.homedir(), '.config', 'mux', 'dashboard.py') },
+  { src: 'config/dashboard-wrapper.sh', dest: path.join(os.homedir(), '.config', 'mux', 'dashboard-wrapper.sh'), mode: 0o755 },
+  { src: 'config/sidebar-wrapper.sh', dest: path.join(os.homedir(), '.config', 'mux', 'sidebar-wrapper.sh'), mode: 0o755 },
+  { src: 'config/status-indicators.sh', dest: path.join(os.homedir(), '.config', 'mux', 'status-indicators.sh'), mode: 0o755 },
+  { src: 'config/context-help.py', dest: path.join(os.homedir(), '.config', 'mux', 'context-help.py') },
+  { src: 'config/show-notes.py', dest: path.join(os.homedir(), '.config', 'mux', 'show-notes.py') },
+  { src: 'config/manage-notes.py', dest: path.join(os.homedir(), '.config', 'mux', 'manage-notes.py') },
+  { src: 'config/manage-dx.py', dest: path.join(os.homedir(), '.config', 'mux', 'manage-dx.py') },
+  { src: 'config/show-dx.py', dest: path.join(os.homedir(), '.config', 'mux', 'show-dx.py') },
+  { src: 'config/mux-server.py', dest: path.join(os.homedir(), '.config', 'mux', 'mux-server.py') },
+  { 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') },
+];
+
+const DATA_DIRS = [
+  path.join(os.homedir(), '.local', 'share', 'mux', 'trails'),
+  path.join(os.homedir(), '.local', 'share', 'mux', 'status'),
+  path.join(os.homedir(), '.config', 'mux', 'notes'),
+  path.join(os.homedir(), '.config', 'mux', 'dx'),
+  path.join(os.homedir(), '.config', 'mux', 'pending-prompts'),
+];
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return 1;
+    if (va < vb) return -1;
+  }
+  return 0;
+}
+
+function readGlobalManifest() {
+  if (!fs.existsSync(GLOBAL_MANIFEST_PATH)) return { files: {} };
+  try {
+    return JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+  } catch {
+    return { files: {} };
+  }
+}
+
+function writeGlobalManifest(manifest) {
+  fs.mkdirSync(path.dirname(GLOBAL_MANIFEST_PATH), { recursive: true });
+  const tmp = GLOBAL_MANIFEST_PATH + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+  fs.renameSync(tmp, GLOBAL_MANIFEST_PATH);
+}
+
+function readInstalledVersion() {
+  if (!fs.existsSync(MUX_VERSION_FILE)) return null;
+  try {
+    return fs.readFileSync(MUX_VERSION_FILE, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeVersion(version) {
+  fs.mkdirSync(path.dirname(MUX_VERSION_FILE), { recursive: true });
+  fs.writeFileSync(MUX_VERSION_FILE, version + '\n');
+}
+
+/**
+ * @param {Object} opts
+ * @param {boolean} [opts.dryRun]
+ * @param {string} [opts.projectDir] — consumer project dir (unused for mux)
+ * @returns {{ results: string[], status: string }}
+ */
+function setupMux(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const results = [];
+
+  const ccVersion = require('../package.json').version;
+  const templateDir = path.resolve(__dirname, '..', 'templates', 'mux');
+
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`mux-setup: ${templateDir} not found.`);
+  }
+
+  const installedVersion = readInstalledVersion();
+
+  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}`);
+  } else {
+    results.push(`Installing mux ${ccVersion}`);
+  }
+
+  // Create data directories
+  for (const dir of DATA_DIRS) {
+    if (!fs.existsSync(dir)) {
+      if (dryRun) {
+        results.push(`  [dry-run] mkdir -p ${dir}`);
+      } else {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  // Copy managed files
+  const manifest = readGlobalManifest();
+  let copiedCount = 0;
+
+  for (const file of MANAGED_FILES) {
+    const srcPath = path.join(templateDir, file.src);
+    if (!fs.existsSync(srcPath)) {
+      results.push(`  ⚠ Template missing: ${file.src}`);
+      continue;
+    }
+
+    const content = fs.readFileSync(srcPath);
+    const hash = sha256(content);
+
+    if (manifest.files[file.dest] === hash) {
+      continue; // file unchanged
+    }
+
+    if (dryRun) {
+      results.push(`  [dry-run] ${file.src} → ${file.dest}`);
+    } else {
+      fs.mkdirSync(path.dirname(file.dest), { recursive: true });
+      fs.writeFileSync(file.dest, content);
+      if (file.mode) {
+        fs.chmodSync(file.dest, file.mode);
+      }
+      manifest.files[file.dest] = hash;
+    }
+    copiedCount++;
+  }
+
+  if (!dryRun) {
+    manifest.version = ccVersion;
+    manifest.installedAt = new Date().toISOString();
+    writeGlobalManifest(manifest);
+    writeVersion(ccVersion);
+  }
+
+  results.push(`  ${copiedCount} file${copiedCount !== 1 ? 's' : ''} installed to user paths`);
+
+  return { results, status: installedVersion ? 'upgraded' : 'installed' };
+}
+
+module.exports = { setupMux };

package/lib/settings-merge.js

@@ -82,6 +82,31 @@ const DEFAULT_HOOKS = {
   ],
 };
 
+const WATCHTOWER_HOOKS = {
+  SessionStart: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: '$HOME/.claude-cabinet/watchtower/hooks/watchtower-session-start.sh',
+        },
+      ],
+    },
+  ],
+  SessionEnd: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: '$HOME/.claude-cabinet/watchtower/hooks/watchtower-session-end.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.
@@ -209,4 +234,34 @@ function healUserSettings() {
   return removed;
 }
 
-module.exports = { mergeSettings, healUserSettings, DEFAULT_HOOKS, LEGACY_HOOK_COMMANDS };
+/**
+ * Merge watchtower-specific hooks into project settings.
+ * Called from the watchtower module's install path in cli.js — only
+ * registers SessionStart/SessionEnd hooks when watchtower is installed.
+ */
+function mergeWatchtowerHooks(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(WATCHTOWER_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, DEFAULT_HOOKS, WATCHTOWER_HOOKS, LEGACY_HOOK_COMMANDS };

package/package.json

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

package/templates/cabinet/committees.yaml

@@ -30,6 +30,7 @@ committees:
       - architecture
       - automation
       - boundary-man
+      - elegance
 
   health:
     name: "System Health"

package/templates/cabinet/watchtower-contracts.md

@@ -0,0 +1,87 @@
+# Watchtower Contracts
+
+Shared contracts for all watchtower components. Every ring, hook, and
+skill that reads or writes watchtower state files must follow these.
+
+## Atomic Writes
+
+All shared files use temp+rename. No exceptions. Write to a `.tmp`
+sibling, then `fs.renameSync()`. This prevents partial reads when a
+ring is writing while a SessionStart hook is reading.
+
+```javascript
+const tmp = filePath + '.tmp';
+fs.writeFileSync(tmp, content);
+fs.renameSync(tmp, filePath);
+```
+
+## No-Index Convention
+
+The decision 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
+listing exceeds 2 seconds or 500 items, revisit via `act:2b638b02`.
+
+## Schema Versioning
+
+Every JSON file carries `schema_version`. Readers guard on version
+and emit clear errors on unrecognized versions. Never silent wrong
+behavior — if a reader sees `schema_version: 2` and only understands
+`1`, it must fail loudly, not silently misparse.
+
+```javascript
+if (item.schema_version !== 1) {
+  throw new Error(`Unsupported schema version ${item.schema_version} in ${filePath}`);
+}
+```
+
+## Session-ID Join Key
+
+Session IDs are the join key across queue items (via `transcript_ref`),
+messages (Plan 8), and Ring 3 cursors (Plan 7). This is a load-bearing
+assumption documented here so that if session IDs prove to be the wrong
+unit (e.g., Claude Code changes ID semantics), the migration scope is
+known: queue items, messages, and cursors all need updating.
+
+Validate when Ring 3 first writes real data.
+
+## Summary Hard Cap
+
+`state/summary.md` must not exceed 30 lines. This is the SessionStart
+injection payload — it competes with other context for the model's
+attention window. If content exceeds 30 lines, truncation order:
+
+1. Drop Health section detail (keep one-line summary)
+2. Drop Portfolio Pulse detail for quiet projects
+3. Never truncate "What Needs Attention" or "Where You Left Off"
+
+## Enrichment Directory
+
+Per-item enrichment lives in `queue/items/<id>/enrichment/`. Four
+standard files:
+
+| File | Written by | Content |
+|------|-----------|---------|
+| `code-context.md` | Ring 2 fast | Actual code being discussed |
+| `related-decisions.md` | Ring 2 fast | Prior decisions bearing on this |
+| `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"`.
+Missing files degrade gracefully (null in the read result).
+
+## Deferred Schemas
+
+The following are specified in project notes but NOT formalized until
+their owning plan ships:
+
+| Schema | Owner | Ships with |
+|--------|-------|-----------|
+| `messages/<session-id>.json` | Plan 8 | Session-directed messages |
+| `ring3/cursors/<session-id>.json` | Plan 7 | Ring 3 live mode |
+| `hooks/<ring>-<phase>.d/` | Plan 9 | Lifecycle hooks |
+| `logs/<ring>.log` | Plan 4 | Ring 1 runner |
+| `lock/<ring>.pid` | Plan 4 | Ring 1 runner |