create-claude-cabinet 0.27.0 → 0.27.2

package/README.md

@@ -186,7 +186,7 @@ absent to use the default. No config files, no YAML, no DSL.
 
 ## Adding Modules to an Existing Install
 
-Some modules (like `verify` and `memory`) are opt-in. To add one
+Some modules (like `verify`) are opt-in. To add one
 without touching anything else in your install:
 
 ```
@@ -196,7 +196,7 @@ npx create-claude-cabinet --modules verify --yes
 The `--modules` flag **merges** with your existing install — it adds
 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,memory`.
+customization. You can pass multiple modules: `--modules verify,audit`.
 
 ## CLI Options
 

package/lib/cli.js

@@ -343,6 +343,15 @@ function generateSkillIndex(projectDir) {
   return entries.length;
 }
 
+// MODULES is the manifest: every template path here is copied into a
+// consumer's project on install. A skill/hook/script that exists under
+// templates/ but is NOT listed in any module never ships — that is the
+// orphan bug that left the whole built-in-memory layer uninstalled
+// before v0.27.2 (test/manifest-integrity guards against recurrence).
+//
+// Intentional orphans (maintainer-only, must NOT ship to consumers) are
+// allowlisted in test/manifest-integrity. Currently: skills/cc-publish
+// (CC-source-repo release tooling, like scripts/migrate-all-consumers.js).
 const MODULES = {
   'session-loop': {
     name: 'Session Loop (orient + debrief)',
@@ -367,7 +376,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: true,
-    templates: ['hooks/git-guardrails.sh', 'hooks/cc-upstream-guard.sh', 'hooks/skill-telemetry.sh', 'hooks/skill-tool-telemetry.sh', 'hooks/work-tracker-guard.sh', 'hooks/action-quality-gate.sh', 'hooks/action-completion-gate.sh', 'hooks/domain-memories.sh', 'scripts/cc-drift-check.cjs'],
+    templates: ['hooks/git-guardrails.sh', 'hooks/cc-upstream-guard.sh', 'hooks/skill-telemetry.sh', 'hooks/skill-tool-telemetry.sh', 'hooks/work-tracker-guard.sh', 'hooks/action-quality-gate.sh', 'hooks/action-completion-gate.sh', 'hooks/memory-index-guard.sh', 'scripts/cc-drift-check.cjs'],
   },
   'work-tracking': {
     name: 'Work Tracking (pib-db or markdown)',
@@ -394,6 +403,27 @@ const MODULES = {
     lean: false,
     templates: ['rules/enforcement-pipeline.md', 'memory/patterns/_pattern-template.md', 'memory/patterns/pattern-intelligence-first.md'],
   },
+  'memory': {
+    name: 'Built-In Memory (cc-remember + reader + validator)',
+    description: 'Curated write/validate layer over Claude Code\'s built-in file memory. /cc-remember writes indexed memories, /memory browses them, validate-memory.mjs guards MEMORY.md integrity. Replaced the retired omega engine in v0.27.',
+    mandatory: false,
+    default: true,
+    // lean:true is load-bearing — it keeps the skill triad, scripts, and
+    // rule installing together as an atomic unit. compliance is lean:false,
+    // so the memory-capture rule must NOT live there or lean installs get a
+    // partial, incoherent set.
+    lean: true,
+    templates: [
+      'skills/cc-remember',
+      'skills/memory',
+      'rules/memory-capture.md',
+      'scripts/write-memory-file.mjs',
+      'scripts/validate-memory.mjs',
+      // project-context.cjs ships as a co-located sibling: the two .mjs
+      // scripts require('./project-context.cjs') and consumers have no lib/.
+      'scripts/project-context.cjs',
+    ],
+  },
   'audit': {
     name: 'Audit Loop (audit + triage + cabinet)',
     description: '27 expert cabinet members review your project. Convene the full cabinet or just one committee.',

package/lib/migrate-from-omega.js

@@ -549,6 +549,111 @@ function buildEdgesJson(edges) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Merge mode — additive, never clobbers native memory
+// ---------------------------------------------------------------------------
+
+const OMEGA_SUBDIR = 'omega-migrated';
+
+/**
+ * Build the MEMORY.md section that indexes omega topic files living under
+ * the omega-migrated/ subdir. Carries the preamble marker so a re-run
+ * detects already-migrated. Paths are prefixed with the subdir.
+ */
+function buildMergeSection(topicFileMeta, summary) {
+  const lines = [
+    PREAMBLE_MARKER,
+    '',
+    `## Migrated from omega (${new Date().toISOString().slice(0, 10)})`,
+    '',
+    `_${summary.migrated} memories migrated from omega into \`${OMEGA_SUBDIR}/\`. ` +
+      `Native memory files above are unchanged. ${summary.edges} edges in ${OMEGA_SUBDIR}/edges.json._`,
+    '',
+  ];
+  for (const { topic, file, count } of topicFileMeta) {
+    const desc = describeTopic(topic);
+    lines.push(`- [${topic}](${OMEGA_SUBDIR}/${file}) (${count}) — ${desc}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Additive merge: write omega topic files into an omega-migrated/ subdir
+ * (zero filename collision with native files), back up the existing dir
+ * first, and append/create a MEMORY.md section indexing them. Never
+ * overwrites a native file.
+ *
+ * @returns {{ backupDir, omegaDir, indexedInto }}
+ */
+function mergeIntoExisting(outputDir, topicFiles, edgesJson, mergeSection, opts = {}) {
+  const omegaDir = path.join(outputDir, OMEGA_SUBDIR);
+  const memoryMdPath = path.join(outputDir, 'MEMORY.md');
+
+  // GUARD: never clobber whatever already occupies the subdir path. If it
+  // exists, it is either a native item the user named `omega-migrated/`, or
+  // residue from an interrupted prior merge. We cannot safely tell them
+  // apart, and the cost of guessing wrong is permanent loss of native data.
+  // Refuse and instruct — the caller surfaces this as a failure with the
+  // native dir fully intact (nothing has been written yet at this point).
+  if (fs.existsSync(omegaDir)) {
+    throw new Error(
+      `Refusing to merge: '${OMEGA_SUBDIR}/' already exists at ${omegaDir}. ` +
+        `If it is leftover from an interrupted migration, remove it and re-run. ` +
+        `If it is your own data, rename it first, then re-run.`
+    );
+  }
+
+  // 1. Back up the existing memory dir wholesale, to a guaranteed-fresh path,
+  //    BEFORE any destructive step. Never proceed without a backup taken
+  //    this invocation (a stale/reused backup wouldn't reflect pristine
+  //    native state).
+  let backupDir = opts.backupDir;
+  if (!backupDir) {
+    const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-');
+    const base = `${outputDir}.pre-omega-merge-${stamp}`;
+    backupDir = base;
+    for (let n = 1; fs.existsSync(backupDir); n++) backupDir = `${base}-${n}`;
+  } else if (fs.existsSync(backupDir)) {
+    throw new Error(`Refusing to merge: backup path ${backupDir} already exists.`);
+  }
+  fs.cpSync(outputDir, backupDir, { recursive: true });
+
+  // 2. Write omega topic files + edges into the subdir (atomic via staging
+  //    rename of the subdir). omegaDir is known absent from the guard above.
+  const stagingDir = path.join(outputDir, `.${OMEGA_SUBDIR}-staging-${process.pid}`);
+  fs.rmSync(stagingDir, { recursive: true, force: true });
+  fs.mkdirSync(stagingDir, { recursive: true });
+  for (const [name, content] of Object.entries(topicFiles)) {
+    fs.writeFileSync(path.join(stagingDir, name), content, 'utf8');
+  }
+  if (edgesJson) fs.writeFileSync(path.join(stagingDir, 'edges.json'), edgesJson, 'utf8');
+  fs.renameSync(stagingDir, omegaDir);
+
+  // 3. Append/create MEMORY.md with the omega section (preamble marker
+  //    included so re-runs detect already-migrated). Idempotent: if the
+  //    marker is somehow already present, do not append a second section.
+  let indexedInto;
+  if (fs.existsSync(memoryMdPath)) {
+    const existing = fs.readFileSync(memoryMdPath, 'utf8');
+    if (existing.includes(PREAMBLE_MARKER)) {
+      indexedInto = 'already-indexed';
+    } else {
+      const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+      const merged = existing + sep + mergeSection;
+      const tmp = memoryMdPath + '.tmp-' + process.pid;
+      fs.writeFileSync(tmp, merged, 'utf8');
+      fs.renameSync(tmp, memoryMdPath);
+      indexedInto = 'appended-to-existing';
+    }
+  } else {
+    const header = `# Memory Index\n\n_Native memory files in this directory predate the index; Claude reads them on demand._\n\n`;
+    fs.writeFileSync(memoryMdPath, header + mergeSection, 'utf8');
+    indexedInto = 'created-new';
+  }
+
+  return { backupDir, omegaDir, indexedInto };
+}
+
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -564,19 +669,17 @@ async function migrateFromOmega(opts = {}) {
   const currentProject = opts.currentProject || resolveCurrentProject(cwd, homeDir);
   const outputDir = resolveOutputDir({ ...opts, cwd, homeDir });
 
+  // Determine write mode. Foreign content (native memory present, no
+  // migration preamble) triggers MERGE — additive, never clobbers — so
+  // omega memories land alongside native memory instead of being skipped.
+  let mode = 'fresh';
   if (!opts.force) {
     const existing = checkExistingMigration(outputDir);
     if (existing.state === 'migrated') {
       return { migrated: 0, reason: 'already-migrated', outputDir };
     }
     if (existing.state === 'foreign-content' || existing.state === 'partial-or-foreign') {
-      return {
-        migrated: 0,
-        reason: existing.state,
-        outputDir,
-        details: existing.files || ['MEMORY.md without migration preamble'],
-        hint: 'Inspect outputDir. If safe to overwrite, re-run with { force: true }.',
-      };
+      mode = 'merge';
     }
   }
 
@@ -587,6 +690,10 @@ async function migrateFromOmega(opts = {}) {
     const { memories, edges } = readVault(vaultDir);
 
     if (memories.length === 0) {
+      // Nothing to migrate. In merge mode, leave native memory untouched.
+      if (mode === 'merge') {
+        return { migrated: 0, reason: 'empty-db', outputDir, mode: 'merge', noop: true };
+      }
       const minimalIndex = `${PREAMBLE_MARKER}\n# Memory Index\n\n_Source: migrated from omega on ${new Date()
         .toISOString()
         .slice(0, 10)}. No prior memories migrated — omega database was empty._\n`;
@@ -636,11 +743,7 @@ async function migrateFromOmega(opts = {}) {
     }
 
     const memoryMd = buildMemoryMd(topicFileMeta, summary);
-    filesToWrite['MEMORY.md'] = memoryMd;
-
-    if (edges.length > 0) {
-      filesToWrite['edges.json'] = buildEdgesJson(edges);
-    }
+    const edgesJson = edges.length > 0 ? buildEdgesJson(edges) : null;
 
     if (opts.dryRun) {
       return {
@@ -648,13 +751,39 @@ async function migrateFromOmega(opts = {}) {
         edges: edges.length,
         outputDir,
         dryRun: true,
+        mode,
         topicFiles: topicFileMeta,
-        memoryMdPreview: memoryMd,
+        memoryMdPreview: mode === 'merge' ? buildMergeSection(topicFileMeta, summary) : memoryMd,
         omegaBin,
         currentProject,
       };
     }
 
+    if (mode === 'merge') {
+      const mergeSection = buildMergeSection(topicFileMeta, summary);
+      const { backupDir, omegaDir, indexedInto } = mergeIntoExisting(
+        outputDir,
+        filesToWrite,
+        edgesJson,
+        mergeSection,
+        opts
+      );
+      return {
+        migrated: memories.length,
+        edges: edges.length,
+        outputDir,
+        mode: 'merge',
+        backupDir,
+        omegaDir,
+        indexedInto,
+        topicFiles: topicFileMeta,
+        currentProject,
+      };
+    }
+
+    // Fresh write (empty dir, or force clobber).
+    filesToWrite['MEMORY.md'] = memoryMd;
+    if (edgesJson) filesToWrite['edges.json'] = edgesJson;
     const stagingDir = path.join(path.dirname(outputDir), STAGING_PREFIX + process.pid);
     writeStaging(stagingDir, filesToWrite);
     commitStaging(stagingDir, outputDir, { force: opts.force });
@@ -663,6 +792,7 @@ async function migrateFromOmega(opts = {}) {
       migrated: memories.length,
       edges: edges.length,
       outputDir,
+      mode: 'fresh',
       topicFiles: topicFileMeta,
       currentProject,
     };

package/lib/migrate-memory-cmd.js

@@ -221,15 +221,20 @@ async function stepMigrateMemories(ctx) {
   if (result.reason === 'already-migrated') {
     return { action: `memories already migrated; reusing existing output at ${result.outputDir}` };
   }
-  if (result.reason === 'foreign-content' || result.reason === 'partial-or-foreign') {
-    return {
-      action: `migrate-from-omega refused: ${result.reason} at ${result.outputDir}. ` +
-        `Hint: ${result.hint || 'inspect manually'}. Continuing — omega cleanup steps will still run.`,
-    };
-  }
   if (result.reason === 'empty-db') {
+    if (result.mode === 'merge') {
+      return { action: `omega DB was empty; native memory at ${result.outputDir} left untouched` };
+    }
     return { action: `omega DB was empty; minimal MEMORY.md written at ${result.outputDir}` };
   }
+  if (result.mode === 'merge') {
+    return {
+      action:
+        `merged ${result.migrated} omega memories (${result.edges || 0} edges) into existing native ` +
+        `memory at ${result.outputDir} (omega content under omega-migrated/; backup at ${result.backupDir}). ` +
+        `Native memories preserved.`,
+    };
+  }
   return {
     action: `migrated ${result.migrated} memories (${result.edges || 0} edges) → ${result.outputDir}`,
   };

package/lib/settings-merge.js

@@ -70,6 +70,15 @@ const DEFAULT_HOOKS = {
         },
       ],
     },
+    {
+      matcher: 'Edit|Write',
+      hooks: [
+        {
+          type: 'command',
+          command: '.claude/hooks/memory-index-guard.sh',
+        },
+      ],
+    },
   ],
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"
@@ -24,7 +24,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "node --test test/**/*.test.js",
+    "prepublishOnly": "node -e \"if (!process.env.CC_ALLOW_PUBLISH) { console.error('\\n\\u2717 Use /cc-publish (which runs the mandatory consumer-walk), not raw npm publish.\\n  Raw npm publish on v0.27.1 left every consumer stale on v0.26.\\n  To publish manually anyway, set CC_ALLOW_PUBLISH=1.\\n'); process.exit(1); }\""
   },
   "dependencies": {
     "better-sqlite3": "^12.8.0",

package/templates/scripts/project-context.cjs

@@ -0,0 +1,103 @@
+/**
+ * Shared project-identity and memory-dir resolution for CC's
+ * memory-related tooling. Used by:
+ *   - lib/migrate-from-omega.js (Phase 1 migration)
+ *   - scripts/write-memory-file.mjs (Phase 3a /cc-remember writer)
+ *   - scripts/validate-memory.mjs (Phase 3a validator)
+ *
+ * Worktree-safe: resolves project identity via `git rev-parse
+ * --git-common-dir`, so callers from a worktree write to the host
+ * project's memory dir, not a per-worktree split.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execSync } = require('node:child_process');
+
+/**
+ * Resolve the absolute path of the current project's primary checkout.
+ * Worktree-safe via git common-dir; falls back to cwd if not in a repo.
+ */
+function resolveProjectAbsolutePath(cwd = process.cwd()) {
+  try {
+    const commonDir = execSync('git rev-parse --git-common-dir', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    }).trim();
+    const abs = path.isAbsolute(commonDir) ? commonDir : path.resolve(cwd, commonDir);
+    return path.dirname(abs);
+  } catch {
+    return path.resolve(cwd);
+  }
+}
+
+/**
+ * Project slug — the basename of the project root. Used as a
+ * human-readable identifier and to match memory keys.
+ */
+function resolveProjectSlug(cwd = process.cwd()) {
+  return path.basename(resolveProjectAbsolutePath(cwd));
+}
+
+/**
+ * Convert an absolute path to Claude Code's project-dir slug format
+ * (dashified). `/Users/x/claude-cabinet` → `-Users-x-claude-cabinet`.
+ */
+function dashifiedSlug(absolutePath) {
+  return absolutePath.replace(/^\//, '-').replace(/\//g, '-');
+}
+
+/**
+ * Read settings.json safely; returns {} on absence or parse error.
+ */
+function readSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve the memory directory for the current project.
+ * Honors `autoMemoryDirectory` setting if present in ~/.claude/settings.json.
+ * Otherwise uses platform default: ~/.claude/projects/<dashified>/memory/.
+ *
+ * Rejects literal `~` in autoMemoryDirectory — Claude Code does NOT
+ * expand tilde in settings.json values, and a silent `./~/...` directory
+ * is a footgun.
+ */
+function resolveMemoryDir(opts = {}) {
+  const homeDir = opts.homeDir || os.homedir();
+  const cwd = opts.cwd || process.cwd();
+  const settingsPath = opts.settingsPath || path.join(homeDir, '.claude', 'settings.json');
+
+  if (opts.memoryDir) return path.resolve(opts.memoryDir);
+
+  const settings = readSettings(settingsPath);
+  if (settings.autoMemoryDirectory) {
+    const v = settings.autoMemoryDirectory;
+    if (v.includes('~')) {
+      throw new Error(
+        `autoMemoryDirectory in ${settingsPath} contains '~' (literal). Claude Code does not expand tilde. Use an absolute path.`
+      );
+    }
+    return path.resolve(v);
+  }
+
+  const projectAbs = resolveProjectAbsolutePath(cwd);
+  return path.join(homeDir, '.claude', 'projects', dashifiedSlug(projectAbs), 'memory');
+}
+
+module.exports = {
+  resolveProjectAbsolutePath,
+  resolveProjectSlug,
+  resolveMemoryDir,
+  dashifiedSlug,
+  readSettings,
+};

package/templates/scripts/validate-memory.mjs

@@ -0,0 +1,207 @@
+/**
+ * Validate the structural integrity of a Claude Code memory directory.
+ *
+ * Checks:
+ *   1. MEMORY.md exists and is within Claude Code's session-start
+ *      load budget: ≤200 lines AND ≤25KB.
+ *   2. Every .md file in the memory dir (except MEMORY.md, edges.json)
+ *      is referenced by MEMORY.md (bidirectional: no orphans).
+ *   3. Every file referenced in MEMORY.md exists on disk.
+ *   4. Topic-style files (migrated from omega) do not exceed 50KB.
+ *      Per-file curated style: no size cap.
+ *
+ * Wired into /validate via templates/skills/validate/phases/validators.md.
+ * Also runs PostToolUse on memory-dir writes via
+ * templates/.claude/hooks/memory-index-guard.sh.
+ *
+ * Exit codes:
+ *   0 — pass
+ *   1 — one or more violations
+ *   2 — bad usage / inaccessible memory dir
+ *
+ * @module scripts/validate-memory
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { resolveMemoryDir } = require('./project-context.cjs');
+
+const MEMORY_INDEX_FILE = 'MEMORY.md';
+const MEMORY_INDEX_LINE_CAP = 200;
+const MEMORY_INDEX_BYTE_CAP = 25_000;
+const TOPIC_FILE_SIZE_CAP = 50_000;
+const NON_MEMORY_FILES = new Set(['MEMORY.md', 'edges.json', '.DS_Store']);
+
+// Files that match this pattern are "topic-style" (multi-memory files
+// produced by Phase 1 migration). The 50KB cap applies to them.
+// Per-file curated style files (one memory each) are not size-capped.
+const TOPIC_FILE_NAMES = new Set([
+  'decisions.md',
+  'lessons.md',
+  'preferences.md',
+  'constraints.md',
+  'session-summaries.md',
+  'subagent-residue.md',
+  'unscoped.md',
+]);
+const TOPIC_FILE_PATTERNS = [
+  /^(decisions|lessons|preferences|constraints|session-summaries|subagent-residue|unscoped)(-recent|-archive)?(-\d+)?\.md$/,
+  /^cross-[a-z0-9_-]+(-recent|-archive)?(-\d+)?\.md$/,
+];
+
+function isTopicStyleFile(name) {
+  if (TOPIC_FILE_NAMES.has(name)) return true;
+  return TOPIC_FILE_PATTERNS.some((re) => re.test(name));
+}
+
+/**
+ * Extract all `.md` filenames referenced from MEMORY.md.
+ * Handles both index formats:
+ *   - Topic-files: `- **decisions.md** (56 entries) — desc`
+ *   - Curated:    `- [Title](file.md) — desc`
+ */
+function parseMemoryIndex(memoryMdText) {
+  const refs = new Set();
+  // Topic-files format: bolded filename
+  for (const m of memoryMdText.matchAll(/\*\*([a-z0-9_.-]+\.md)\*\*/gi)) {
+    refs.add(m[1]);
+  }
+  // Curated format: markdown link
+  for (const m of memoryMdText.matchAll(/\]\(([a-z0-9_.-]+\.md)\)/gi)) {
+    refs.add(m[1]);
+  }
+  return refs;
+}
+
+/**
+ * Validate one memory directory.
+ *
+ * @returns {{ violations: string[], warnings: string[], stats: object }}
+ */
+export function validateMemoryDir(opts = {}) {
+  const memoryDir = opts.memoryDir
+    ? path.resolve(opts.memoryDir)
+    : resolveMemoryDir({ homeDir: opts.homeDir, cwd: opts.cwd, settingsPath: opts.settingsPath });
+
+  const violations = [];
+  const warnings = [];
+  const stats = { memoryDir };
+
+  if (!fs.existsSync(memoryDir)) {
+    return {
+      violations: [`memory directory does not exist: ${memoryDir}`],
+      warnings,
+      stats,
+    };
+  }
+
+  const indexPath = path.join(memoryDir, MEMORY_INDEX_FILE);
+  if (!fs.existsSync(indexPath)) {
+    return {
+      violations: [`${MEMORY_INDEX_FILE} missing under ${memoryDir}`],
+      warnings,
+      stats,
+    };
+  }
+
+  const indexText = fs.readFileSync(indexPath, 'utf8');
+  const indexBytes = Buffer.byteLength(indexText, 'utf8');
+  const indexLines = indexText.split('\n').length;
+  stats.indexLines = indexLines;
+  stats.indexBytes = indexBytes;
+
+  if (indexLines > MEMORY_INDEX_LINE_CAP) {
+    violations.push(
+      `MEMORY.md exceeds line cap: ${indexLines} lines (max ${MEMORY_INDEX_LINE_CAP}). Reduce index verbosity or move details into topic files.`
+    );
+  }
+  if (indexBytes > MEMORY_INDEX_BYTE_CAP) {
+    violations.push(
+      `MEMORY.md exceeds byte cap: ${indexBytes} bytes (max ${MEMORY_INDEX_BYTE_CAP}). Reduce index verbosity.`
+    );
+  }
+
+  const referenced = parseMemoryIndex(indexText);
+  stats.indexedFileCount = referenced.size;
+
+  const entries = fs.readdirSync(memoryDir).filter((f) => !f.startsWith('.'));
+  const onDiskMd = entries.filter((f) => f.endsWith('.md') && !NON_MEMORY_FILES.has(f));
+  stats.onDiskMemoryFileCount = onDiskMd.length;
+
+  // Orphans on disk (file exists, not indexed).
+  for (const f of onDiskMd) {
+    if (!referenced.has(f)) {
+      violations.push(
+        `orphan memory file: ${f} exists in ${memoryDir} but is not referenced by MEMORY.md. ` +
+          `Either reference it (manually or via /cc-remember next time) or delete it.`
+      );
+    }
+  }
+
+  // Broken references (indexed but missing on disk).
+  for (const ref of referenced) {
+    if (ref === MEMORY_INDEX_FILE) continue;
+    if (!entries.includes(ref)) {
+      violations.push(
+        `broken reference in MEMORY.md: ${ref} is indexed but does not exist on disk.`
+      );
+    }
+  }
+
+  // Size cap on topic-style files.
+  for (const f of onDiskMd) {
+    if (!isTopicStyleFile(f)) continue;
+    const bytes = fs.statSync(path.join(memoryDir, f)).size;
+    if (bytes > TOPIC_FILE_SIZE_CAP) {
+      violations.push(
+        `topic file too large: ${f} is ${bytes} bytes (cap ${TOPIC_FILE_SIZE_CAP}). Re-shard via migration tool or split manually.`
+      );
+    }
+  }
+
+  return { violations, warnings, stats };
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  let memoryDir = null;
+  let quiet = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--memory-dir' || args[i] === '--dir') memoryDir = args[++i];
+    else if (args[i] === '--quiet') quiet = true;
+    else if (args[i] === '--help' || args[i] === '-h') {
+      console.log('usage: validate-memory.mjs [--memory-dir <path>] [--quiet]');
+      console.log('  Validates a Claude Code memory directory. Defaults to the');
+      console.log('  current project\'s memory dir. Exits 0 on pass, 1 on violations.');
+      process.exit(0);
+    }
+  }
+  try {
+    const { violations, warnings, stats } = validateMemoryDir({ memoryDir });
+    if (!quiet) {
+      console.log(`memory-dir: ${stats.memoryDir}`);
+      if (stats.indexLines !== undefined) {
+        console.log(`MEMORY.md:  ${stats.indexLines} lines / ${stats.indexBytes} bytes`);
+      }
+      if (stats.onDiskMemoryFileCount !== undefined) {
+        console.log(`on disk:    ${stats.onDiskMemoryFileCount} files`);
+        console.log(`indexed:    ${stats.indexedFileCount} references`);
+      }
+    }
+    for (const w of warnings) console.warn(`WARN: ${w}`);
+    for (const v of violations) console.error(`FAIL: ${v}`);
+    if (violations.length > 0) {
+      console.error(`\nvalidate-memory: ${violations.length} violation(s)`);
+      process.exit(1);
+    }
+    if (!quiet) console.log('validate-memory: PASS');
+    process.exit(0);
+  } catch (e) {
+    console.error('validate-memory failed:', e.message);
+    process.exit(2);
+  }
+}

package/templates/scripts/write-memory-file.mjs

@@ -0,0 +1,185 @@
+/**
+ * Write a single memory file under the project's memory dir and
+ * update MEMORY.md's index to reference it.
+ *
+ * This is the per-file curated-style writer: each memory is its own
+ * .md file with a descriptive slug, matching Claude Code's native
+ * auto-memory convention. Used by /cc-remember and (Phase 3b) by
+ * debrief's record-lessons phase.
+ *
+ * Does NOT depend on omega — works against the file-based memory
+ * layout regardless of whether omega is installed.
+ *
+ * @module scripts/write-memory-file
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { resolveMemoryDir } = require('./project-context.cjs');
+
+const MEMORY_INDEX_FILE = 'MEMORY.md';
+const CURATED_SECTION_HEADER = '## Curated entries (hand-authored)';
+const CURATED_SECTION_BODY =
+  '_Hand-curated memory files. Each is one memory, written by Claude or you. Loaded on demand when Claude references them below._\n';
+
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,79}$/;
+
+/**
+ * Normalize an input string to a valid slug.
+ * Lowercase, alphanumeric + underscore + hyphen, 1-80 chars,
+ * starts with alphanumeric. Strips leading/trailing punctuation.
+ */
+export function normalizeSlug(input) {
+  if (!input || typeof input !== 'string') {
+    throw new Error('slug: input must be a non-empty string');
+  }
+  const normalized = input
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9_-]+/g, '_')
+    .replace(/^[_-]+|[_-]+$/g, '')
+    .slice(0, 80);
+  if (!normalized || !SLUG_RE.test(normalized)) {
+    throw new Error(`slug "${input}" could not be normalized to a valid filename`);
+  }
+  return normalized;
+}
+
+/**
+ * Write a memory file. If a file with the same slug exists, append
+ * a date suffix until unique (slug.md → slug_2026-05-27.md →
+ * slug_2026-05-27-2.md).
+ *
+ * @param {object} opts
+ * @param {string} opts.slug — descriptive identifier for the memory
+ * @param {string} opts.content — markdown body
+ * @param {string} [opts.title] — optional `# Title` heading; defaults
+ *   to a title-cased version of the slug
+ * @param {string} [opts.description] — one-line description for the
+ *   MEMORY.md index entry (recommended; defaults to first line of content)
+ * @param {string} [opts.memoryDir] — override the resolved memory dir
+ * @param {string} [opts.homeDir] — override $HOME (for tests)
+ * @param {string} [opts.cwd] — override cwd (for tests)
+ * @param {string} [opts.settingsPath] — override settings.json path
+ * @param {Date|string} [opts.date] — override "today" for testing
+ * @returns {{filePath: string, slug: string, indexed: boolean, bytesWritten: number}}
+ */
+export function writeMemoryFile(opts = {}) {
+  if (!opts.content || typeof opts.content !== 'string') {
+    throw new Error('writeMemoryFile: content is required and must be a string');
+  }
+  if (!opts.slug) {
+    throw new Error('writeMemoryFile: slug is required (provide via opts.slug or via /cc-remember --slug)');
+  }
+
+  const slug = normalizeSlug(opts.slug);
+  const memoryDir = opts.memoryDir
+    ? path.resolve(opts.memoryDir)
+    : resolveMemoryDir({ homeDir: opts.homeDir, cwd: opts.cwd, settingsPath: opts.settingsPath });
+
+  fs.mkdirSync(memoryDir, { recursive: true });
+
+  const date = opts.date ? new Date(opts.date) : new Date();
+  const dateStr = date.toISOString().slice(0, 10);
+
+  // Resolve filename, avoiding collision via date + counter suffix.
+  let fileName = `${slug}.md`;
+  let counter = 1;
+  while (fs.existsSync(path.join(memoryDir, fileName))) {
+    counter++;
+    fileName = counter === 2
+      ? `${slug}_${dateStr}.md`
+      : `${slug}_${dateStr}-${counter - 1}.md`;
+  }
+
+  const finalSlug = fileName.replace(/\.md$/, '');
+  const filePath = path.join(memoryDir, fileName);
+
+  const title = opts.title || finalSlug.replace(/[_-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  const body = [`# ${title}`, '', `_Captured: ${dateStr}_`, '', opts.content.trim(), ''].join('\n');
+
+  // Atomic write via temp + rename.
+  const tmpPath = filePath + '.tmp-' + process.pid;
+  fs.writeFileSync(tmpPath, body, 'utf8');
+  fs.renameSync(tmpPath, filePath);
+
+  const description = opts.description || extractFirstLine(opts.content) || title;
+  const indexed = updateMemoryIndex({ memoryDir, fileName, title, description });
+
+  return {
+    filePath,
+    slug: finalSlug,
+    indexed,
+    bytesWritten: Buffer.byteLength(body, 'utf8'),
+  };
+}
+
+function extractFirstLine(text) {
+  for (const raw of text.split('\n')) {
+    const line = raw.trim().replace(/^[-*#>\s]+/, '');
+    if (line) return line.slice(0, 100);
+  }
+  return null;
+}
+
+/**
+ * Add an entry for `fileName` to MEMORY.md's curated-entries section.
+ * Creates the section if absent. If the file is already indexed
+ * anywhere (Topic files OR Curated entries section), no-op.
+ *
+ * Returns true if MEMORY.md was modified, false if no change needed.
+ */
+function updateMemoryIndex({ memoryDir, fileName, title, description }) {
+  const indexPath = path.join(memoryDir, MEMORY_INDEX_FILE);
+  let body = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '# Memory Index\n\n';
+
+  // Idempotency: don't re-index a file already referenced anywhere.
+  if (body.includes(`(${fileName})`) || body.includes(`**${fileName}**`)) {
+    return false;
+  }
+
+  const entry = `- [${title}](${fileName}) — ${description}`;
+
+  if (body.includes(CURATED_SECTION_HEADER)) {
+    body = body.replace(CURATED_SECTION_HEADER, `${CURATED_SECTION_HEADER}\n${entry}`);
+  } else {
+    const trailing = body.endsWith('\n') ? '' : '\n';
+    body = `${body}${trailing}\n${CURATED_SECTION_HEADER}\n\n${CURATED_SECTION_BODY}\n${entry}\n`;
+  }
+
+  const tmp = indexPath + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, body, 'utf8');
+  fs.renameSync(tmp, indexPath);
+  return true;
+}
+
+// CLI mode: `node scripts/write-memory-file.mjs --slug foo "content..."`
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  let slug = null;
+  let title = null;
+  let description = null;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--slug') slug = args[++i];
+    else if (args[i] === '--title') title = args[++i];
+    else if (args[i] === '--description') description = args[++i];
+    else positional.push(args[i]);
+  }
+  const content = positional.join(' ');
+  if (!slug || !content) {
+    console.error('usage: write-memory-file.mjs --slug <slug> [--title <title>] [--description <desc>] <content>');
+    process.exit(2);
+  }
+  try {
+    const result = writeMemoryFile({ slug, content, title, description });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (e) {
+    console.error('write-memory-file failed:', e.message);
+    process.exit(1);
+  }
+}

package/templates/skills/cc-publish/SKILL.md

@@ -63,7 +63,10 @@ With user confirmation:
 1. Update `version` in `package.json`
 2. Commit: `Bump to <version>`
 3. Tag: `git tag v<version>`
-4. `npm publish`
+4. `CC_ALLOW_PUBLISH=1 npm publish` — the `prepublishOnly` guard blocks
+   a bare `npm publish` (raw publish on v0.27.1 left every consumer
+   stale on v0.26); the env var is the deliberate escape, and reaching
+   this step via /cc-publish guarantees Step 6's consumer walk follows.
 5. `git push && git push --tags`
 
 ### 5. Post-Publish

package/templates/skills/cc-upgrade/phases/omega-migration-detect.md

@@ -17,6 +17,10 @@ Return true if ANY of:
 4. `~/.claude/settings.json.mcpServers` or
    `~/.claude.json.mcpServers` has any key matching
    `/^omega(-memory)?$/i` OR any command containing `omega-venv`
+5. Any inert omega file artifact remains in the project (a migration
+   that tore down the venv/hooks/MCP can still leave these on disk):
+   `.claude/hooks/omega-memory-guard.sh`, `.claude/hooks/domain-memories.sh`,
+   `scripts/cabinet-memory-adapter.py`, `scripts/migrate-memory-to-omega.py`
 
 Full detection check:
 
@@ -38,10 +42,35 @@ for p in ['$HOME/.claude/settings.json', '$HOME/.claude.json']:
         pass
 raise SystemExit(1)
 " 2>/dev/null && HAS_OMEGA=1
+for f in .claude/hooks/omega-memory-guard.sh .claude/hooks/domain-memories.sh \
+         scripts/cabinet-memory-adapter.py scripts/migrate-memory-to-omega.py; do
+  test -f "$f" && HAS_OMEGA=1
+done
 ```
 
 If `HAS_OMEGA=1`, proceed. If 0, skip this phase silently.
 
+## Inert-artifact sweep (always runs when this phase proceeds)
+
+A consumer whose omega was already migrated (`migrated_from_omega.state
+=== 'complete'`, venv/hooks/MCP gone) can still carry inert omega files
+that the teardown didn't remove. Remove them by exact name. This is
+idempotent — `rm -f` no-ops when the file is absent, so it's safe to
+run on every cc-upgrade:
+
+```bash
+rm -f .claude/hooks/omega-memory-guard.sh \
+      .claude/hooks/domain-memories.sh \
+      scripts/cabinet-memory-adapter.py \
+      scripts/migrate-memory-to-omega.py
+```
+
+Report which files were actually removed (test before/after, or capture
+`rm -v` output). Only remove these exact paths — do not glob or remove
+anything else. If omega is still ACTIVE (conditions 1–4 above), run the
+full migration flow below FIRST; the sweep cleans up what teardown
+leaves behind, it does not replace migration.
+
 ## User-friendly prompt
 
 Default to **dry-run** — a non-Oren user just upgrading CC shouldn't