create-claude-cabinet 0.23.1 → 0.25.0

package/README.md

@@ -5,7 +5,7 @@ gives Claude a memory, 31 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
-was built by Claude. I just complained until it worked.
+was built by Claude. I just complained until it (mostly) worked.
 
 ## The Idea
 
@@ -63,8 +63,8 @@ automatically.
 
 - **`/orient`** — open every session with this. Claude reads project
   state, checks health, surfaces what needs attention, and briefs you
-  so you never start blind. Think of it as the morning briefing before
-  the cabinet gets to work.
+  so you never start blind. Think of it as the briefing before the
+  cabinet gets to work.
 - **`/debrief`** — close every session with this. Claude marks work
   done, records lessons, updates state, and prepares the briefing for
   next time. Without debrief, the next orient starts with stale
@@ -134,7 +134,7 @@ hooks — things that keep going wrong become things that can't go wrong.
 
 ## Your Workflow
 
-The day-to-day rhythm:
+The rhythm of each session:
 
 1. **Start a session** → `/orient` (get briefed)
 2. **Do your work** → talk to Claude, use `/plan` for anything non-trivial
@@ -227,7 +227,7 @@ other.
 ## Philosophy
 
 This started as the process layer of [Flow](https://github.com/orenmagid/flow),
-a cognitive workspace built on Claude Code over months of daily use. The
+a cognitive workspace built on Claude Code over months of intensive use. The
 patterns that emerged — the session loop, cabinet-style audits, feedback
 enforcement — turned out to be transferable to any project.
 

package/lib/cli.js

@@ -8,6 +8,7 @@ const { mergeSettings } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupOmega } = require('./omega-setup');
+const { setupVerifyRuntime } = require('./verify-setup');
 const { reset } = require('./reset');
 
 const VERSION = require('../package.json').version;
@@ -356,6 +357,7 @@ const MODULES = {
       // 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/menu',
     ],
@@ -450,6 +452,20 @@ const MODULES = {
     needsOmega: true,
     templates: ['skills/memory', 'scripts/cabinet-memory-adapter.py', 'scripts/migrate-memory-to-omega.py', 'rules/memory-capture.md', 'hooks/omega-memory-guard.sh'],
   },
+  'verify': {
+    name: 'Verification Harness (Cucumber + Playwright)',
+    description: 'Walkthrough verification with human-in-the-loop verdict pauses. Replaces flat AC lists with re-runnable user-journey scenarios. Includes /verify skeleton skill + cabinet-verify npm runtime + opt-in integration phases for /plan, /execute, /debrief.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    templates: [
+      'skills/verify',
+      'skills/plan/phases/verify-plan.md',
+      'skills/execute/phases/verify-emit.md',
+      'skills/debrief/phases/verify-coverage.md',
+    ],
+    postInstall: 'verify-setup',
+  },
 };
 
 /** Recursively collect all relative file paths under a directory. */
@@ -503,7 +519,8 @@ function parseArgs(argv) {
     targetDir: '.',
   };
 
-  for (const arg of args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === '--yes' || arg === '-y') flags.yes = true;
     else if (arg === '--lean') flags.lean = true;
     else if (arg === '--no-db') flags.noDb = true;
@@ -511,6 +528,9 @@ function parseArgs(argv) {
     else if (arg === '--help' || arg === '-h') flags.help = true;
     else if (arg === '--reset') flags.reset = true;
     else if (arg === '--force') flags.force = true;
+    else if (arg === '--modules' && i + 1 < args.length) {
+      flags.modules = args[++i].split(',').map(s => s.trim()).filter(Boolean);
+    }
     else if (!arg.startsWith('-')) flags.targetDir = arg;
   }
 
@@ -525,6 +545,8 @@ function printHelp() {
     --yes, -y     Accept all defaults, no prompts
     --lean        Install core modules only (no work-tracking, compliance, validate)
     --no-db       Skip work tracking database setup
+    --modules <keys>  Comma-separated module keys to install (e.g., 'verify,memory').
+                  Mandatory modules are always included.
     --dry-run     Show what would be copied without writing
     --reset       Remove Claude Cabinet files (uses manifest for safety)
     --force       With --reset: remove even customized files
@@ -664,7 +686,27 @@ async function run() {
   let skippedModules = {};
   let includeDb = !flags.noDb;
 
-  if (flags.lean) {
+  if (flags.modules) {
+    // Explicit module selection via --modules <key1,key2,...>. Mandatory
+    // modules are always included regardless of the flag value, so the
+    // installer always has session-loop etc. available.
+    const mandatoryKeys = Object.entries(MODULES)
+      .filter(([, mod]) => mod.mandatory)
+      .map(([key]) => key);
+    const requested = flags.modules.filter(k => MODULES[k]);
+    const unknown = flags.modules.filter(k => !MODULES[k]);
+    if (unknown.length > 0) {
+      console.log(`  ⚠ Unknown modules ignored: ${unknown.join(', ')}`);
+      console.log(`    Known modules: ${Object.keys(MODULES).join(', ')}`);
+    }
+    selectedModules = [...new Set([...mandatoryKeys, ...requested])];
+    const skippedKeys = Object.keys(MODULES).filter(k => !selectedModules.includes(k));
+    for (const k of skippedKeys) {
+      skippedModules[k] = `Skipped by --modules flag`;
+    }
+    if (!selectedModules.includes('work-tracking')) includeDb = false;
+    console.log(`  Installing modules: ${selectedModules.join(', ')}\n`);
+  } else if (flags.lean) {
     selectedModules = Object.entries(MODULES)
       .filter(([, mod]) => mod.mandatory || mod.lean)
       .map(([key]) => key);
@@ -954,6 +996,26 @@ async function run() {
     }
   }
 
+  // --- Run module postInstall hooks ---
+  // Modules with a `postInstall` field dispatch to a matching setup
+  // function after templates are copied. Currently only 'verify-setup'
+  // (the cabinet-verify tarball builder) is wired.
+  for (const moduleKey of selectedModules) {
+    const mod = MODULES[moduleKey];
+    if (!mod.postInstall) continue;
+    if (mod.postInstall === 'verify-setup') {
+      try {
+        console.log('');
+        const verifyResult = setupVerifyRuntime({ dryRun: !!flags.dryRun });
+        for (const r of verifyResult.results || []) console.log(`  📋 ${r}`);
+      } catch (err) {
+        console.log(`  ⚠ cabinet-verify runtime setup failed: ${err.message}`);
+        console.log('    /verify install.sh will fail until the runtime is installed.');
+        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/verify-setup.js

@@ -0,0 +1,140 @@
+/**
+ * verify-setup.js — install the cabinet-verify runtime tarball at
+ * ~/.claude-cabinet/verify/<version>/dist/.
+ *
+ * Mirrors the omega-setup.js pattern: dispatched from cli.js's install
+ * pipeline when the `verify` module is selected. Idempotent: skips if
+ * the matching-version tarball is already present.
+ *
+ * See templates/verify-runtime/CONVENTIONS.md §Install Dir and
+ * §Tarball Install Pattern for the frozen contract this implements.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
+const VERIFY_BASE = path.join(CC_HOME, 'verify');
+
+/**
+ * Set up the cabinet-verify runtime.
+ *
+ * Steps:
+ * 1. Read the version from templates/verify-runtime/package.json
+ * 2. Compute installDir = ~/.claude-cabinet/verify/<version>/dist/
+ * 3. If a tarball already exists at that path with the same version,
+ *    log "already installed" and skip
+ * 4. Otherwise: mkdir -p installDir; npm pack inside templates/verify-runtime/;
+ *    move the .tgz to installDir
+ * 5. Write ~/.claude-cabinet/verify/current/VERSION (single-line pointer
+ *    used by /verify install.sh per CONVENTIONS.md Version Resolution)
+ *
+ * @param {Object} opts
+ * @param {boolean} [opts.dryRun] — print planned actions, don't execute
+ * @param {string} [opts.runtimeSourceDir] — override the templates/verify-runtime/
+ *   location. Defaults to <repo>/templates/verify-runtime/ resolved from __dirname.
+ * @returns {Object} { installPath, version, status: 'installed'|'skipped'|'dry-run' }
+ */
+function setupVerifyRuntime(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const runtimeSourceDir =
+    opts.runtimeSourceDir || path.resolve(__dirname, '..', 'templates', 'verify-runtime');
+
+  // 1. Read version
+  const packageJsonPath = path.join(runtimeSourceDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(
+      `verify-setup: ${packageJsonPath} not found. Cannot resolve cabinet-verify version.`,
+    );
+  }
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const version = pkg.version;
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(`verify-setup: ${packageJsonPath} has no version field`);
+  }
+
+  // 2. Compute installDir
+  const installDir = path.join(VERIFY_BASE, version, 'dist');
+  const tarballName = `cabinet-verify-${version}.tgz`;
+  const tarballPath = path.join(installDir, tarballName);
+  const versionPointer = path.join(VERIFY_BASE, 'current', 'VERSION');
+
+  const results = [];
+
+  if (dryRun) {
+    results.push(`Would install cabinet-verify@${version}`);
+    results.push(`  source:  ${runtimeSourceDir}`);
+    results.push(`  target:  ${tarballPath}`);
+    results.push(`  pointer: ${versionPointer}`);
+    return { installPath: installDir, version, status: 'dry-run', results };
+  }
+
+  // 3. Idempotency check. Existence alone is not enough — an earlier
+  // stub-touch (e.g., a test fixture) can leave a 0-byte file at the
+  // tarball path. npm install on the consumer side then fails with
+  // ENODATA / TAR_BAD_ARCHIVE. Validate the file has non-trivial size
+  // before treating it as installed.
+  if (fs.existsSync(tarballPath) && fs.statSync(tarballPath).size > 1024) {
+    results.push(`cabinet-verify@${version} already installed (${tarballPath})`);
+    // Even on skip, ensure the VERSION pointer is up-to-date so a later
+    // version downgrade doesn't leave a stale pointer behind.
+    writeVersionPointer(versionPointer, version);
+    results.push(`Updated VERSION pointer: ${versionPointer}`);
+    return { installPath: installDir, version, status: 'skipped', results };
+  }
+
+  // Remove a 0-byte stub before re-packing so the move below doesn't
+  // hit a "file exists" surprise.
+  if (fs.existsSync(tarballPath)) {
+    fs.unlinkSync(tarballPath);
+  }
+
+  // 4. mkdir + npm pack + move
+  fs.mkdirSync(installDir, { recursive: true });
+  // Run npm pack in the runtime source dir. --pack-destination writes
+  // the tarball directly to installDir without an intermediate cwd move.
+  const packStdout = execSync(`npm pack --silent --pack-destination "${installDir}"`, {
+    cwd: runtimeSourceDir,
+    encoding: 'utf8',
+  }).trim();
+
+  // npm pack prints the tarball filename to stdout on the last non-empty line.
+  // Normalise to the expected name so consuming projects can rely on the
+  // CONVENTIONS.md-documented path.
+  const lastLine = packStdout.split('\n').filter(Boolean).pop() || '';
+  const producedName = path.basename(lastLine);
+  if (producedName && producedName !== tarballName) {
+    // npm pack may produce a name like 'cabinet-verify-0.1.0.tgz' that already
+    // matches; if it doesn't (e.g., npm prefixes with @scope/), rename to match.
+    const producedPath = path.join(installDir, producedName);
+    if (fs.existsSync(producedPath)) {
+      fs.renameSync(producedPath, tarballPath);
+    }
+  }
+
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error(
+      `verify-setup: npm pack completed but ${tarballPath} not found. ` +
+        `stdout was: ${packStdout.slice(0, 500)}`,
+    );
+  }
+
+  results.push(`Installed cabinet-verify@${version} to ${tarballPath}`);
+
+  // 5. Write VERSION pointer
+  writeVersionPointer(versionPointer, version);
+  results.push(`Wrote VERSION pointer: ${versionPointer}`);
+
+  return { installPath: installDir, version, status: 'installed', results };
+}
+
+function writeVersionPointer(pointerPath, version) {
+  fs.mkdirSync(path.dirname(pointerPath), { recursive: true });
+  // No trailing newline — CONVENTIONS.md frozen contract requires the
+  // file to equal the version string exactly under `cat`.
+  fs.writeFileSync(pointerPath, version, 'utf8');
+}
+
+module.exports = { setupVerifyRuntime };

package/package.json

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

package/templates/skills/debrief/SKILL.md

@@ -306,27 +306,24 @@ Don't silently bundle unrelated changes.
 
 ### 9. Record Lessons (core)
 
-Read `phases/record-lessons.md` for how to capture what was learned.
-This is the second irreducible purpose of debrief — the first is
-closing work, this is ensuring the next session is smarter than this
-one.
-
-**Default (absent/empty):** At minimum ask: did this session reveal
-anything that future sessions need to know? A new pattern, a gotcha,
-a process gap, a user preference? Lessons are perishable — capture
-them now while context is fresh.
-
-**Omega-only:** If `~/.claude-cabinet/omega-venv/bin/python3` and
-`scripts/cabinet-memory-adapter.py` both exist, write lessons to omega
-— never to flat markdown. A guard hook enforces this. Use the adapter:
-
-```bash
-echo '{"text": "the lesson", "type": "lesson"}' | \
-  ~/.claude-cabinet/omega-venv/bin/python3 scripts/cabinet-memory-adapter.py store
-```
-
-Types: `decision`, `lesson`, `preference`, `constraint`, `pattern`.
-Flat markdown memory is the fallback only when omega is unavailable.
+Read `phases/record-lessons.md` for how to route session outputs to
+their real homes. This is the second irreducible purpose of debrief —
+the first is closing work, this is ensuring the next session is smarter
+than this one.
+
+**The phase file teaches a routing discipline:** every output has
+exactly one home with a forcing function — omega `decision`/`lesson`/
+`constraint`/`preference` memory, inline in CLAUDE.md or a briefing
+(for load-bearing project facts), a pib-db deferred action (for
+conditional revisits), or the upstream-feedback phase (for CC-applicable
+friction). Loose `.md` files written next to the code they describe
+are explicitly an **anti-pattern** — they rot silently when the code
+changes. Hybrid observations (part project, part CC) must be split.
+
+**Default (absent/empty):** Follow the routing tree in the phase file.
+Ask the user only when routing is genuinely ambiguous — not as a
+catch-all "what did we learn?" prompt, which tends to produce vague
+lessons that don't get recorded anywhere useful.
 
 **Omega broken:** If the memory module is installed (check `.ccrc.json`
 for `"memory": true`) but the venv or adapter is missing, surface this
@@ -485,7 +482,7 @@ Read `phases/report.md` for how to present the debrief summary.
 | `auto-maintenance.md` | Skip | Recurring session-end tasks |
 | `update-state.md` | Default: check system-status.md | What state files to update |
 | `health-checks.md` | Skip | Session-end health checks |
-| `record-lessons.md` | Default: ask what was learned | How to capture learnings |
+| `record-lessons.md` | Default: route outputs per the decision tree | How to route session outputs to omega / CLAUDE.md / pib-db triggers / upstream |
 | `audit-pattern-capture.md` | **Instruction: always runs** | Detect recurring audit findings, write to patterns-project.md |
 | `methodology-capture.md` | **Instruction: always runs** | Detect methodology-level work; capture reasoning chain + narrative to `.claude/methodology/` |
 | `upstream-feedback.md` | **Instruction: always runs** | Surface CC friction to source repo |

package/templates/skills/debrief/phases/record-lessons.md

@@ -1,94 +1,173 @@
-# Record Lessons — Capture What Was Learned
+# Record Lessons — Route Session Outputs to Their Real Homes
 
-Define how to capture lessons from the session so future sessions are
-smarter. This is the second irreducible purpose of debrief — without it,
-the system does work but doesn't learn from it.
+This is debrief's second irreducible purpose: make sure the next session
+is smarter than this one. Without it, the system does work but doesn't
+learn from it.
 
-When this file is absent or empty, the default behavior is: ask whether
-the session revealed anything future sessions need to know. To explicitly
-skip lesson recording, write only `skip: true`.
+Lessons are perishable. A lesson captured while context is fresh is
+worth ten captured from memory next week.
 
-Lessons are perishable. A lesson captured while context is fresh is worth
-ten captured from memory next week. This is why recording happens during
-debrief, not "sometime later."
+## The Routing Principle
 
-## Where to Record — Omega Primary
+Every session output has **exactly one primary home**. The home must
+have a forcing function — something that keeps the content accurate
+when the code it describes changes. Loose `.md` files next to code
+are the wrong home: they rot silently because nothing invalidates
+them when the system evolves.
 
-Check whether omega memory is available:
-- `~/.claude-cabinet/omega-venv/bin/python3` exists AND
-- `scripts/cabinet-memory-adapter.py` exists
+**Each output has one home. Don't double-store.** A decision stored
+in omega doesn't also need a `.md` file. A constraint documented in
+CLAUDE.md doesn't also need an omega entry "for backup." Duplication
+just creates two things to keep in sync.
 
-**When omega is available — use it. No exceptions.** Write lessons to
-omega via the adapter. Never write to flat markdown memory files when
-omega is available — a guard hook will block the attempt.
+## Routing Decision Tree
+
+For each thing you'd want future sessions to know, pick the single
+best home:
+
+### Decisions — "we chose X over Y because Z"
+
+Architectural choices, tradeoff resolutions, accepted gaps, rejected
+alternatives.
+
+**Primary home:** omega `decision` memory. Omega has contradiction
+detection — when a later decision supersedes this one, the old entry
+can be marked `status=superseded` instead of silently rotting.
 
 ```bash
-echo '{"text": "the lesson", "type": "lesson", "tags": ["tag1"]}' | \
+echo '{"text": "the decision + why", "type": "decision"}' | \
   ~/.claude-cabinet/omega-venv/bin/python3 scripts/cabinet-memory-adapter.py store
 ```
 
-Memory types to use:
-- `decision` — architectural choices, tradeoff resolutions
-- `lesson` — gotchas, discoveries, things that surprised
-- `preference` — user corrections, style choices, workflow preferences
-- `constraint` — limitations discovered, prerequisites found
-- `pattern` — conventions established, recurring solutions
-
-**When omega is NOT available:** Only then use flat markdown memory
-(auto-memory in `~/.claude/projects/` memory directory). Check omega
-availability first — don't assume it's unavailable without checking.
-
-## What to Look For
-
-Review the session and ask:
-- Did we learn something future sessions need to know?
-  - A new pattern established
-  - A gotcha discovered
-  - A process gap identified
-  - A user preference revealed
-- Is this the second or third time something came up? If the same kind
-  of problem keeps recurring, the lesson is "create a prevention mechanism"
-  not just "remember this."
-- Did the session's work contradict any existing recorded knowledge?
-  If so, update or remove the stale record (in omega: use `query` to
-  find it, then note the contradiction in the new memory).
-
-## What NOT to Record
-- Code patterns derivable by reading current files
-- Git history (use git log)
-- Debugging solutions (the fix is in the code)
-- Anything already in CLAUDE.md files
-- Ephemeral task details only relevant to this session
+**Also add to CLAUDE.md** only if the decision is load-bearing enough
+that *every* session needs to know it at startup (not just sessions
+that touch the relevant code). Examples: "auth is per-user via FastAPI
+Users (no shared passwords)" is load-bearing. "We rejected a specific
+library option after evaluation" is not — omega is enough.
 
-## After Storing — Link and Check
+### Project constraints / conventions / gotchas
 
-After storing each memory, omega auto-relates it to similar existing
-memories. Surface this to the user:
+Environmental quirks, dev-workflow requirements, "this project has a
+weird setup" facts.
 
-```bash
-~/.claude-cabinet/omega-venv/bin/python3 -c "
-from omega import find_similar_memories
-result = find_similar_memories('THE_NEW_MEMORY_ID')
-print(result)
-"
+**Primary home:** inline in `CLAUDE.md` or the project briefing. These
+files get edited when the code changes — the forcing function is that
+they're load-bearing for every session, so staleness surfaces fast.
+
+Use omega `constraint` type only for cross-project patterns (e.g.,
+"in any project with nested package.json..."). Project-specific
+constraints belong inline.
+
+### Conditional revisits — "do X later when Y happens"
+
+"If we ever get multiple concurrent users, add a token blocklist."
+"When curl becomes annoying, build a /settings UI."
+
+**Primary home:** pib-db deferred action with `trigger_condition`.
+
+```
+pib_create_action text="..." status="deferred" trigger_condition="..."
 ```
 
-If the new memory is similar to existing ones, mention it:
-"This connects to your earlier memory about [topic]."
+Orient's deferred-check phase re-evaluates these every session. If the
+condition has fired, the user gets asked; if it's obsolete, it gets
+marked so. No silent rot.
+
+### CC upstream friction embedded in a project observation
+
+Sometimes a project-scoped observation contains a CC-applicable piece:
+"in this project auth tests are hard, AND cabinet-qa should flag this
+pattern in any auth work." That's two things, not one.
+
+**Split it.** Route the project piece to its home (omega / CLAUDE.md /
+trigger). Route the CC piece to the upstream-feedback phase (step 11)
+where it will be drafted and delivered. Don't bury the upstream piece
+inside a project decision doc — it will never find its way home.
+
+### Lessons, gotchas, discoveries (not decisions, not constraints)
+
+"We learned that X behaves differently from docs." "This pattern
+works." "The CI was green but prod failed because…"
+
+**Primary home:** omega `lesson` memory. Same forcing function as
+decisions — superseded lessons can be marked and surfaced.
+
+### User preferences
+
+Style choices, workflow preferences, corrections the user made.
+
+**Primary home:** omega `preference` memory.
 
-Also check for contradictions — if the new memory conflicts with an
-existing one, ask the user which is correct:
+## The Anti-Pattern: Loose Project-Scoped .md Files
+
+**Do not write `feedback-project-*.md`, `decision-*.md`, or similar
+loose .md files as the primary record of a session output.** This
+pattern has been observed to rot — in one audited case, 4 of 5 such
+files went stale within 7 days because the underlying code changed
+and the files had no forcing function to catch it.
+
+If you are tempted to write a loose .md file:
+- Is it a decision? → omega `decision`
+- Is it a constraint everyone needs? → CLAUDE.md / briefing
+- Is it a conditional revisit? → pib-db deferred trigger
+- Is it CC upstream friction? → upstream-feedback phase
+- None of the above? → it probably doesn't need recording at all
+
+## Before Writing — Contradiction Check
+
+For each memory you're about to write, query omega for existing
+entries on the same topic:
+
+```bash
+~/.claude-cabinet/omega-venv/bin/omega query "topic keywords" --limit 5
+```
+
+If an existing entry contradicts or is superseded by the new one,
+mark the old one:
 
 ```bash
-~/.claude-cabinet/omega-venv/bin/python3 -c "
-from omega import SQLiteStore
-s = SQLiteStore()
-edges = s.get_edges_by_type('contradicts')
-for e in edges: print(f\"{e['source_id']} <-> {e['target_id']} ({e['weight']:.2f})\")
-"
+~/.claude-cabinet/omega-venv/bin/omega update <old-id> --status superseded
+```
+
+This is the forcing function that turns omega into a living record
+instead of another pile of rotting notes.
+
+## When Omega Is Not Available
+
+If `~/.claude-cabinet/omega-venv/bin/python3` is missing AND the
+memory module is not installed (check `.ccrc.json`), fall back to
+flat markdown memory in `~/.claude/projects/...`. But recognize
+this fallback has the same rot problem — prefer CLAUDE.md for
+anything load-bearing and pib-db triggers for anything conditional.
+
+If the memory module IS installed but omega is broken, surface this
+in the debrief report:
+
+> **⚠ Memory module is installed but omega is not working.**
+> Decisions/lessons from this session were saved to flat markdown
+> instead. Run `npx create-claude-cabinet` to rebuild the omega venv.
+
+## What NOT to Record — Anywhere
+
+- Code patterns derivable by reading current files
+- Git history (use `git log`)
+- Debugging solutions (the fix is already in the code; the commit
+  message has the context)
+- Anything already in CLAUDE.md files
+- Ephemeral task details only relevant to this session
+- "We made progress on X" session summaries — that's what git is for
+
+## Report What Was Routed
+
+Tell the user what went where so they can audit the routing:
+
+```
+Routed this session:
+- 1 decision → omega mem-xxxxx (JWT revocation tradeoff)
+- 1 constraint → article-rewriter/CLAUDE.md (tsc must run from frontend)
+- 1 deferred trigger → pib-db act:xxxxxxxx (add blocklist if multi-user)
+- 1 upstream piece → CC feedback outbox (cabinet-qa testability)
 ```
 
-## Report What Was Recorded
-Tell the user what memories were created or updated so they know what
-the system will remember next time. Include the count, types, and any
-new connections discovered in the knowledge graph.
+This is also how you catch routing errors: if everything ended up in
+omega, the routing discipline didn't actually run.