create-claude-cabinet 0.45.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
@@ -256,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

@@ -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;
@@ -632,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',
@@ -655,6 +659,7 @@ const MODULES = {
       'skills/briefing',
       'skills/threads',
       'skills/qa-handoff',
+      'skills/qa-drain',
     ],
   },
   mux: {
@@ -1411,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

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 },
@@ -122,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.`);
@@ -132,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}`);
   }
@@ -200,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 };
 }
 
 /**
@@ -308,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,
+};

package/lib/watchtower-setup.js

@@ -0,0 +1,210 @@
+/**
+ * watchtower-setup.js — keep the GLOBAL watchtower runtime fresh on reinstall.
+ *
+ * The watchtower module copies its files into the PROJECT (the normal module
+ * copy in lib/cli.js). But the GLOBAL runtime at ~/.claude-cabinet/watchtower/
+ * is only ever set up by the manual `/watchtower install` SKILL.md one-time
+ * step. So `npx create-claude-cabinet` (reinstall) refreshed the project files
+ * but NOT the global runtime scripts/docs/hooks — they went stale, and a
+ * brand-new runtime script (e.g. watchtower-advisories.mjs) never appeared
+ * until a hand-copy.
+ *
+ * This installer mirrors lib/mux-setup.js's content-aware refresh: a global
+ * SHA256 manifest at ~/.claude-cabinet/global-manifest.json records each
+ * dest's last-written hash, and only changed-or-new files are copied. Reusing
+ * mux's manifest is safe — entries are keyed by absolute dest path, so the
+ * watchtower dests (~/.claude-cabinet/watchtower/...) never collide with mux's
+ * (~/.config/mux/..., ~/.local/bin/...).
+ *
+ * REFRESH-ONLY semantics (critical): if the runtime directory does NOT already
+ * exist, this returns immediately with status 'absent' and writes nothing.
+ * Fresh runtime setup — launchd plist / cron, config.json, migrate-keys, the
+ * coherence assertion — is the `/watchtower install` SKILL.md step's job and is
+ * NOT replicated here. This function only keeps the code/docs/hooks of an
+ * EXISTING runtime current.
+ *
+ * The .mjs script set is globbed from templates/scripts/watchtower-*.mjs at
+ * load time (single source of truth — a newly shipped runtime script is picked
+ * up automatically; that "new file appears" case was the watchtower-advisories
+ * failure). The shell runners, session hooks, and cabinet docs are mapped
+ * explicitly since they live in different template subtrees and land in
+ * different runtime subdirs.
+ */
+
+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 RUNTIME_DIR = path.join(CC_HOME, 'watchtower');
+const RUNTIME_SCRIPTS_DIR = path.join(RUNTIME_DIR, 'scripts');
+const RUNTIME_HOOKS_DIR = path.join(RUNTIME_DIR, 'hooks');
+const RUNTIME_CABINET_DIR = path.join(RUNTIME_DIR, 'cabinet');
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'templates');
+
+/**
+ * Build the MANAGED_FILES list: { src (absolute), dest (absolute), mode? }.
+ *
+ *   - ALL templates/scripts/watchtower-*.mjs       → runtime scripts/
+ *   - the watchtower shell runners under scripts/   → runtime scripts/ (0o755)
+ *   - templates/hooks/watchtower-session-*.sh       → runtime hooks/   (0o755)
+ *   - the two cabinet docs                          → runtime cabinet/
+ *
+ * Globbing the .mjs set keeps it the single source of truth — no hand-picked
+ * subset that can drift as new runtime scripts ship.
+ */
+function buildManagedFiles() {
+  const files = [];
+  const scriptsDir = path.join(TEMPLATE_DIR, 'scripts');
+
+  // All watchtower runtime .mjs scripts (globbed — complete set, no drift).
+  if (fs.existsSync(scriptsDir)) {
+    for (const name of fs.readdirSync(scriptsDir)) {
+      if (/^watchtower-.*\.mjs$/.test(name)) {
+        files.push({
+          src: path.join(scriptsDir, name),
+          dest: path.join(RUNTIME_SCRIPTS_DIR, name),
+        });
+      }
+    }
+  }
+
+  // Shell runners the runtime executes (cron/launchd target these). They live
+  // in templates/scripts/ and land beside the .mjs in the runtime scripts/ dir.
+  const shellRunners = [
+    'watchtower-ring1-runner.sh',
+    'watchtower-ring2-runner.sh',
+    'watchtower-status.sh',
+  ];
+  for (const name of shellRunners) {
+    files.push({
+      src: path.join(scriptsDir, name),
+      dest: path.join(RUNTIME_SCRIPTS_DIR, name),
+      mode: 0o755,
+    });
+  }
+
+  // Session hooks → runtime hooks/.
+  const hooksDir = path.join(TEMPLATE_DIR, 'hooks');
+  for (const name of ['watchtower-session-start.sh', 'watchtower-session-end.sh']) {
+    files.push({
+      src: path.join(hooksDir, name),
+      dest: path.join(RUNTIME_HOOKS_DIR, name),
+      mode: 0o755,
+    });
+  }
+
+  // Cabinet docs the runtime / advisory pass reads → runtime cabinet/.
+  const cabinetDir = path.join(TEMPLATE_DIR, 'cabinet');
+  for (const name of ['advisories-state-schema.md', 'watchtower-contracts.md']) {
+    files.push({
+      src: path.join(cabinetDir, name),
+      dest: path.join(RUNTIME_CABINET_DIR, name),
+    });
+  }
+
+  return files;
+}
+
+const MANAGED_FILES = buildManagedFiles();
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function readGlobalManifest() {
+  if (!fs.existsSync(GLOBAL_MANIFEST_PATH)) return { files: {} };
+  try {
+    const m = JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+    // Guard shape drift: manifest.files is indexed unconditionally below.
+    if (typeof m !== 'object' || m === null || Array.isArray(m)) return { files: {} };
+    if (typeof m.files !== 'object' || m.files === null || Array.isArray(m.files)) m.files = {};
+    return m;
+  } 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);
+}
+
+/**
+ * Refresh the code/docs/hooks of an EXISTING watchtower runtime, content-aware.
+ *
+ * @param {Object} opts
+ * @param {boolean} [opts.dryRun]
+ * @param {string[]} [opts.results] — human-readable lines are pushed here; a
+ *   fresh array is created and returned when not supplied.
+ * @returns {{ results: string[], status: 'absent'|'unchanged'|'refreshed' }}
+ */
+function refreshWatchtowerRuntime(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const results = opts.results || [];
+
+  // Refresh-only: never bootstrap a fresh runtime here. Fresh setup (launchd,
+  // cron, config.json, migrate-keys, coherence assertion) is the
+  // `/watchtower install` SKILL.md step's job. No runtime dir ⇒ no-op.
+  if (!fs.existsSync(RUNTIME_DIR)) {
+    return { results, status: 'absent' };
+  }
+
+  results.push('Refreshing watchtower runtime (content-aware)');
+
+  const manifest = readGlobalManifest();
+  let copiedCount = 0;
+
+  for (const file of MANAGED_FILES) {
+    if (!fs.existsSync(file.src)) {
+      results.push(`  ⚠ Template missing: ${file.src}`);
+      continue;
+    }
+
+    const content = fs.readFileSync(file.src);
+    const hash = sha256(content);
+
+    if (manifest.files[file.dest] === hash) {
+      continue; // file unchanged
+    }
+
+    if (dryRun) {
+      results.push(`  [dry-run] ${path.relative(TEMPLATE_DIR, 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 && copiedCount > 0) {
+    manifest.installedAt = new Date().toISOString();
+    writeGlobalManifest(manifest);
+  }
+
+  if (copiedCount > 0) {
+    results.push(`  ${copiedCount} runtime file${copiedCount !== 1 ? 's' : ''} refreshed under ${RUNTIME_DIR}`);
+    return { results, status: 'refreshed' };
+  }
+
+  results.push('  watchtower runtime already current');
+  return { results, status: 'unchanged' };
+}
+
+// MANAGED_FILES, RUNTIME_DIR, and TEMPLATE_DIR are exported for the
+// runtime-refresh test so it can seed a faithful, complete global manifest
+// (single source of truth — the test never re-derives the file list).
+module.exports = {
+  refreshWatchtowerRuntime,
+  MANAGED_FILES,
+  RUNTIME_DIR,
+  TEMPLATE_DIR,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"
@@ -22,6 +22,10 @@
   ],
   "author": "Oren Magid",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orenmagid/claude-cabinet.git"
+  },
   "engines": {
     "node": ">=18"
   },

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

@@ -27,7 +27,10 @@ briefing:
   # Common: .claude/cabinet/_briefing-architecture.md, _briefing-jurisdictions.md, _briefing-api.md
 standing-mandate: audit
   # Add plan, execute, orient, debrief if this member should activate
-  # in those contexts. Most members are audit-only.
+  # in those contexts. Most members are audit-only. Two session-boundary
+  # contexts exist for standing advisors (watchtower installs):
+  # session-close (Ring 3's automatic transcript-fed advisor pass) and
+  # briefing (/briefing's live advisor panel).
 tools:
   # List every external tool/command this member uses.
   # Format: "tool-name (scope -- what it does)"
@@ -37,8 +40,10 @@ tools:
   #   - grep patterns (all projects -- dead code detection)
   # Use "tools: []" for pure-reasoning members with no tool stage.
 directives:
-  # Only if standing-mandate includes plan, execute, orient, or debrief.
-  # Each directive is a one-sentence focused task for that context.
+  # Only if standing-mandate includes plan, execute, orient, debrief,
+  # session-close, or briefing. Each directive is a one-sentence focused
+  # task for that context. A mandate without a matching directive is a
+  # data error — consumers skip the member and say so.
   # plan: >
   #   What to evaluate when reviewing a plan.
   # execute: >

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

@@ -1,12 +1,18 @@
 # Advisory dismissal state — schema and rules
 
-Orient surfaces stack-aware advisories (install the Ruby language server, register the Railway MCP, install `hookify`, …). Without memory, every advisory re-nags every session — the same attention-fatigue pattern the watchtower rings were built to eliminate. This file defines the per-project state that gives advisories a memory, and the exact rules orient follows so an advisory is never *permanently* silenced by accident.
+The watchtower **SessionStart context builder** surfaces stack-aware advisories (install the Ruby language server, register the Railway MCP, install `hookify`, …) via `scripts/watchtower-advisories.mjs` (act:f9ea075d). Without memory, every advisory re-nags every session — the same attention-fatigue pattern the watchtower rings were built to eliminate. This file defines the per-project state that gives advisories a memory, and the exact rules the advisory pass follows so an advisory is never *permanently* silenced by accident.
+
+> **Actor.** The owner of these rules is `watchtower-advisories.mjs` (`runAdvisoryPass`), called by the context builder when watchtower is installed. On a project WITHOUT watchtower, orient runs a thin one-shot fallback (it may shell the same module via `node scripts/watchtower-advisories.mjs` when present, else surface basic install hints with no persistent dismissal state). The module is the single implementation of the rules below; do not re-encode them anywhere else.
 
 ## Where it lives
 
-`.claude/cabinet/advisories-state.json` — **per project, generated at runtime**, NOT shipped as a template. Orient creates it on first write. It must never be added to a module's template array: a shipped stub would overwrite a project's real dismissal history on reinstall (the `.ccrc.json` clobber class of bug). If the file is absent, every advisory is treated as never-seen.
+`.claude/cabinet/advisories-state.json` — **per project, generated at runtime**, NOT shipped as a template. The advisory pass creates it on first write. It must never be added to a module's template array: a shipped stub would overwrite a project's real dismissal history on reinstall (the `.ccrc.json` clobber class of bug). If the file is absent OR malformed JSON, every advisory is treated as never-seen (the reader degrades to `{}`, never throws).
+
+> Worktree note: `.claude/cabinet/` is copied per worktree, so dismissal state can diverge between a worktree and its main checkout. That is acceptable — advisories are advisory — and is the reason this is project-local, not user-global. **Path-consistency rule:** the pass reads AND writes the state at the SAME path (the session's `--project-path` cwd). Never read from one path and write to another, or a decline recorded in one place is invisible from the other and the advisory re-nags forever.
+
+## Reserved `_meta` key
 
-> Worktree note: `.claude/cabinet/` is copied per worktree, so dismissal state can diverge between a worktree and its main checkout. That is acceptable — advisories are advisory — and is the reason this is project-local, not user-global.
+`_meta` is a **reserved top-level key**, NOT an advisory entry. It holds pass-level bookkeeping — currently `{ "last_probe": "<UTC YYYY-MM-DD>" }`, the throttle stamp for the `claude plugin list` install-probe (run at most once/day/checkout; UTC to match `last_shown` and sqlite `date('now')`). Any consumer iterating advisory entries (e.g. `Object.entries(state)`) MUST skip `_meta`. No advisory id may be named `_meta`.
 
 ## Schema
 
@@ -30,9 +36,26 @@ Orient surfaces stack-aware advisories (install the Ruby language server, regist
 - **`last_shown`** — ISO date of the most recent surfacing.
 - **`signal`** — *the key field that makes "resurface if the stack changed" actually work.* A short, deterministic fingerprint of the stack indicators present when the advisory was last shown/declined. For a multi-indicator advisory like Ruby (`Gemfile` OR `*.rb`), the fingerprint records *which* indicators were present (e.g. `gemfile` vs `gemfile+rb`), so a later change is detectable. Without this stored snapshot, orient has only the *current* indicators and no baseline to diff against — which is the gap this schema closes.
 
-## The rules orient follows
+## Computing the signal (the indicator fingerprint)
+
+A signal is a deterministic fingerprint of the stack indicators present now. Two rules keep it stable:
+
+- **Sorted tokens.** A multi-indicator advisory joins its present indicators (e.g. Ruby = `gemfile`, `rb`, or `gemfile+rb`) **after sorting** them. Readdir order is not stable; without the sort, `gemfile+rb` and `rb+gemfile` would alternate and spuriously re-arm a declined advisory every session.
+- **Bounded stack scan.** Source-file indicators (`*.ts`, `*.py`, `*.rb`) are detected by a **depth-limited (≤3) walk** with a denylist (`node_modules`, `dist`, `build`, `vendor`, `coverage`, `target`, `out`, plus all dot-dirs) and **early-exit on first match** (existence only). A recursive walk would be pathological on the session-start critical path; a root-only scan would silently miss the common `src/**/*.ts` layout (a TS project with no root `tsconfig.json`).
+
+## The probe is tri-state (the fourth input state)
 
-Before surfacing any advisory, orient computes the advisory's **current signal** (fingerprint of the indicators present now) and reads the stored entry:
+The install-probe (`claude plugin list`) answers "is this plugin installed?" — but it can fail to answer (claude not on PATH, nonzero exit, timeout). Its result is therefore **`true | false | null`**, never a boolean. `null` ("unknown") is a distinct input state and is handled per advisory **kind**:
+
+- **probe-suppressed** (the LSP advisories): the signal is on disk (stack files); the probe only *suppresses* (confirms installed → terminal). `installed===null` → **still surface** from the signal/state rules; freeze only the `installed` transition.
+- **probe-gated** (`plugin:hookify`): the surfacing predicate *is* the probe ("hookify not installed"). `installed===null` → predicate unknowable → **suppress this session, do NOT increment count, do NOT write state** (freeze the entry untouched).
+- **no-probe** (`mcp:railway`, `briefing-file`, `registry-orphan`): pure filesystem/config signal; the probe is irrelevant.
+
+In all kinds, `installed===true` flips the entry to terminal `installed`.
+
+## The rules the advisory pass follows
+
+Before surfacing any advisory, the pass computes the advisory's **current signal** (fingerprint of the indicators present now) and reads the stored entry:
 
 1. **No entry / file absent** → surface it. Write `{status:"suggested", count:1, last_shown:today, signal:current}`.
 2. **`installed`** → never surface (terminal). (Re-probe may flip a `suggested`/`declined` entry to `installed`; never the reverse automatically.)
@@ -64,5 +87,9 @@ Document any new advisory's signal source here when you add it, and call out exp
 | `lsp:rust` | `Cargo.toml` | `/plugin install rust-analyzer-lsp` |
 | `lsp:go` | `go.mod` | `/plugin install gopls-lsp` |
 | `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` | 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**) | `/plugin install hookify` |
+| `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 |
+| `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/composition-patterns.md

@@ -107,9 +107,10 @@ to do its own work. One cabinet member consults another mid-evaluation.
 needs full conversation history) references another cabinet member's known
 findings — from memory, from audit history, or from prior session output.
 
-**Example:** During debrief, a historian cabinet member is activated to check:
-"Has this kind of change been done before? What happened? Are there
-lessons from prior sessions relevant to what was just completed?"
+**Example:** At session close (Ring 3's advisor pass), the historian is
+activated to check: "Has this kind of change been done before? What
+happened? Are there lessons from prior sessions relevant to what was
+just completed?"
 
 **Example:** During planning, the organized-mind cabinet member might need
 the historian's input: "Has this kind of information architecture been