total-recall-brain 3.41.4 → 3.41.6

package/src/core/cli-commands.mjs

@@ -14,6 +14,7 @@ export const CLI_COMMANDS = {
   restore:  'restore.mjs',
   upgrade:  'upgrade.mjs',
   update:   'update.mjs',
+  release:  'release.mjs',
   friction: 'friction.mjs',
   chat:     'chat.mjs',
   status:   'status.mjs',
@@ -22,6 +23,7 @@ export const CLI_COMMANDS = {
   edit:     'edit.mjs',
   recall:   'recall.mjs',
   context:  'context.mjs',
+  compact:  'compact.mjs',
   preflight: 'preflight.mjs',
   'tr-preflight': 'preflight.mjs',
   'context-stats': 'context-stats.mjs',

package/src/core/cli-semantic-index.mjs

@@ -508,13 +508,14 @@ export async function buildCliSemanticIndex({
   skillsDir = null,
   projectRoot = process.cwd(),
   force = false,
-  semantic = true
+  semantic = true,
+  harvest = harvestAllCliVerbs
 } = {}) {
   if (!derivedDir) {
     throw new Error('derivedDir is required to build CLI semantic index');
   }
 
-  const harvested = harvestAllCliVerbs({ projectRoot, skillsDir });
+  const harvested = harvest({ projectRoot, skillsDir });
   const existing = force ? null : loadCliSemanticIndex(derivedDir);
   const existingMap = new Map();
 

package/src/core/conflict-detector.mjs

@@ -291,17 +291,6 @@ export function autoResolveConflict(conflict) {
   const newIsProtected = isProtectedInvariant(newNode);
   const existingIsProtected = isProtectedInvariant(existingNode);
 
-  // Tier 0: New user-created node always wins and auto-supersedes
-  if (newAuth === 'user') {
-    return {
-      resolved: true,
-      action: 'supersede',
-      winner: newNode.slug,
-      loser: existingNode.slug,
-      reason: `User-created candidate node '${newNode.slug}' automatically supersedes existing node '${existingNode.slug}' to keep the developer in the loop within the IDE context.`,
-    };
-  }
-
   // Tier 1: Both are protected invariants — require human review
   if (newIsProtected && existingIsProtected) {
     return {
@@ -318,7 +307,7 @@ export function autoResolveConflict(conflict) {
       action: 'keep',
       winner: existingNode.slug,
       loser: newNode.slug,
-      reason: `Existing node '${existingNode.slug}' is a protected invariant. New node auto-rejected.`,
+      reason: `Existing node '${existingNode.slug}' is a protected invariant. Non-protected node rejected.`,
     };
   }
   if (newIsProtected && !existingIsProtected) {
@@ -331,6 +320,28 @@ export function autoResolveConflict(conflict) {
     };
   }
 
+  // Tier 0: New user-created node always wins against machine-generated node
+  if (newAuth === 'user' && existingAuth === 'machine') {
+    return {
+      resolved: true,
+      action: 'supersede',
+      winner: newNode.slug,
+      loser: existingNode.slug,
+      reason: `User-created candidate node '${newNode.slug}' automatically supersedes existing node '${existingNode.slug}' to keep the developer in the loop within the IDE context.`,
+    };
+  }
+
+  // Tier 0b: New user-created node against other user node (non-protected)
+  if (newAuth === 'user' && existingAuth === 'user') {
+    return {
+      resolved: true,
+      action: 'supersede',
+      winner: newNode.slug,
+      loser: existingNode.slug,
+      reason: `User-created candidate node '${newNode.slug}' automatically supersedes existing user node '${existingNode.slug}' to reflect latest intent.`,
+    };
+  }
+
   // Tier 3: User vs machine — user intent always wins
   if (newAuth === 'user' && existingAuth === 'machine') {
     return {

package/src/core/context-compactor.mjs

@@ -0,0 +1,145 @@
+/** Budgeted task capsules: rank rules, keep verbatim text, and account for every rule left out. */
+
+import { estimateTokens } from './context-policy.mjs';
+import { cosineSimilarity } from './embeddings.mjs';
+
+const DUPLICATE_SIMILARITY = 0.92;
+const REFERENCE_SHARE = 0.4;
+const TOP_FULL_SHARE = 0.3;
+const SUMMARY_MAX_CHARS = 200;
+const SUMMARY_MIN_CHARS = 80;
+// A period here does not end a sentence.
+const SENTENCE_END = /(?<!\be\.g)(?<!\bi\.e)(?<!\bvs)[.!?](?=\s|$)/g;
+
+/** The leading sentences of a rule, verbatim. Never rewords, because rewording can change a constraint. */
+export function summarizeRule(text) {
+  const flat = String(text || '').replace(/^#+\s.*$/gm, ' ').replace(/\s+/g, ' ').trim();
+  if (flat.length <= SUMMARY_MAX_CHARS) return flat;
+  let end = 0;
+  for (const match of flat.matchAll(SENTENCE_END)) {
+    const candidate = match.index + 1;
+    if (candidate > SUMMARY_MAX_CHARS) break;
+    end = candidate;
+    if (end >= SUMMARY_MIN_CHARS) return flat.slice(0, end);
+  }
+  if (end) return flat.slice(0, end);
+  const cut = flat.lastIndexOf(' ', SUMMARY_MAX_CHARS);
+  return `${flat.slice(0, cut > 0 ? cut : SUMMARY_MAX_CHARS)}…`;
+}
+
+/** Relevance alone orders the text; ties fall to importance, then slug, so output is stable. */
+function rank(items) {
+  return [...items].sort((a, b) =>
+    (b.score || 0) - (a.score || 0) ||
+    (b.importance || 3) - (a.importance || 3) ||
+    a.slug.localeCompare(b.slug));
+}
+
+function findDuplicates(ranked) {
+  const duplicateOf = new Map();
+  const normalize = text => String(text).toLowerCase().replace(/\s+/g, ' ').trim();
+  ranked.forEach((item, i) => {
+    if (item.priority === 'absolute') return;
+    for (const earlier of ranked.slice(0, i)) {
+      if (duplicateOf.has(earlier.slug)) continue;
+      const same = normalize(item.body) === normalize(earlier.body) ||
+        (item.vector && earlier.vector && cosineSimilarity(item.vector, earlier.vector) >= DUPLICATE_SIMILARITY);
+      if (same) { duplicateOf.set(item.slug, earlier.slug); return; }
+    }
+  });
+  return duplicateOf;
+}
+
+/**
+ * Assign each rule a tier so the printed output fits `budget`, measuring the real
+ * render after every change. `header(counts, tokens)` supplies the status lines.
+ */
+export function compactRules(items, { budget, expand = [], header, complete = false }) {
+  if (!Number.isFinite(budget) || budget < 1) throw new Error('Compact budget must be a positive token estimate');
+  const ranked = rank(items);
+  const known = new Set(ranked.map(item => item.slug));
+  const unknown = expand.filter(slug => !known.has(slug));
+  if (unknown.length) throw new Error(`Cannot expand rules not in this capsule: ${unknown.join(', ')}`);
+  const duplicateOf = findDuplicates(ranked.filter(item => !expand.includes(item.slug)));
+  const tiers = new Map(ranked.map(item => [item.slug, 'omitted']));
+
+  const render = () => {
+    const of = tier => ranked.filter(item => tiers.get(item.slug) === tier);
+    const full = of('full'), summary = of('summary'), reference = of('reference'), duplicate = of('duplicate');
+    const counts = { rules: ranked.length, full: full.length, summarized: summary.length, referenced: reference.length,
+      duplicate: duplicate.length, omitted: of('omitted').length };
+    const blocks = [
+      ...full.map(item => item.text.trim()),
+      ...summary.map(item => `[${item.slug}] ${summarizeRule(item.body)}`),
+    ];
+    if (reference.length) blocks.push(`Referenced: ${reference.map(item => item.slug).join(', ')}`);
+    if (duplicate.length) blocks.push(`Duplicates: ${duplicate.map(item => `${item.slug} (of ${duplicateOf.get(item.slug)})`).join(', ')}`);
+    const body = blocks.join('\n\n---\n\n');
+    // The token count sits inside the text it counts, so iterate to a stable value.
+    let tokens = estimateTokens(body);
+    let context = '';
+    for (let i = 0; i < 5; i++) {
+      context = `${header(counts, tokens)}${body ? `\n${body}` : ''}`;
+      const measured = estimateTokens(`${context}\n`);
+      if (measured === tokens) break;
+      tokens = measured;
+    }
+    return { context, counts, tokens };
+  };
+  const used = () => render().tokens;
+  const tryTier = (item, tier, limit = budget) => {
+    const previous = tiers.get(item.slug);
+    tiers.set(item.slug, tier);
+    if (used() <= limit) return true;
+    tiers.set(item.slug, previous);
+    return false;
+  };
+
+  // A complete capsule measures its own, higher floor below, so a retry at the reported number succeeds.
+  const floor = used();
+  if (!complete && floor > budget) {
+    const error = new Error(`Budget ${budget} cannot hold the capsule header; the minimum is ${floor}`);
+    error.requiredBudget = floor;
+    error.ruleCount = items.length;
+    throw error;
+  }
+
+  for (const slug of expand) {
+    if (!tryTier(ranked.find(item => item.slug === slug), 'full')) {
+      const error = new Error(`Budget ${budget} cannot hold expanded rule ${slug}; raise --budget or expand fewer rules`);
+      throw error;
+    }
+  }
+  // A complete capsule accounts for every rule before ranking spends any budget, so
+  // ranking decides how much text a rule gets and never whether it applies.
+  if (complete) {
+    for (const item of ranked) {
+      if (tiers.get(item.slug) !== 'omitted') continue;
+      tiers.set(item.slug, duplicateOf.has(item.slug) ? 'duplicate' : item.priority === 'absolute' ? 'summary' : 'reference');
+    }
+    const completeFloor = used();
+    if (completeFloor > budget) {
+      const error = new Error(`Budget ${budget} cannot hold every rule; the minimum is ${completeFloor}`);
+      error.requiredBudget = completeFloor;
+      error.ruleCount = items.length;
+      throw error;
+    }
+  }
+  const candidates = ranked.filter(item => !duplicateOf.has(item.slug) && tiers.get(item.slug) !== 'full');
+
+  // Slugs alone must not consume a small budget: the top rules need their text.
+  const referenceLimit = used() + Math.floor((budget - used()) * REFERENCE_SHARE);
+  // Absolute rules are named first, so a small budget still shows they exist.
+  const unplaced = candidates.filter(item => tiers.get(item.slug) === 'omitted');
+  const namedFirst = [...unplaced.filter(item => item.priority === 'absolute'), ...unplaced.filter(item => item.priority !== 'absolute')];
+  for (const item of namedFirst) if (!tryTier(item, 'reference', referenceLimit)) break;
+  const topLimit = used() + Math.floor((budget - used()) * TOP_FULL_SHARE);
+  for (const item of candidates) tryTier(item, 'full', topLimit);
+  for (const item of candidates) if (tiers.get(item.slug) !== 'full') tryTier(item, 'summary');
+  for (const item of candidates) if (tiers.get(item.slug) !== 'full') tryTier(item, 'full');
+  for (const item of namedFirst) if (tiers.get(item.slug) === 'omitted') tryTier(item, 'reference');
+  for (const slug of duplicateOf.keys()) tryTier(ranked.find(item => item.slug === slug), 'duplicate');
+
+  const { context, counts, tokens } = render();
+  return { context, counts, tokens, tiers: Object.fromEntries(tiers) };
+}

package/src/core/context-policy.mjs

@@ -40,6 +40,24 @@ export function ruleAppliesToRepo(node, repo) {
   return true;
 }
 
+const CRITICAL_TOP_RULES = new Set([
+  'invariants-8cd098fd',
+  'invariants-dc116371',
+  'never-ask-for-a-secret-before-searching-all-tr-stores',
+  'push-only-on-request',
+  'report-breakage-then-fix-at-the-source',
+  'invariants-bbbbec36',
+  'invariants-5d8df45d',
+  'invariants-7780389f',
+  'rule-total-recall-for-everything-always',
+]);
+
+function rulePrecedence(slug) {
+  if (slug === 'invariants-8cd098fd' || slug === 'invariants-dc116371') return 100;
+  if (CRITICAL_TOP_RULES.has(slug)) return 50;
+  return 0;
+}
+
 /** Applicability is explicit validated memory tags, independent of obligation.
  * Unknown rules remain required in task capsules. No inference from prose.
  */
@@ -51,6 +69,7 @@ export function selectRules(nodes, { actions = [], projectRoot = process.cwd(),
     if (!ruleAppliesToRepo(node, repo)) return false;
     const tags = Array.isArray(node.tags) ? node.tags : [];
     if (tags.includes('context:universal')) return true;
+    if (node.priority === 'absolute' || node.immutable === true) return true;
     if (bootstrap) return false;
     const triggers = tags.filter(t => typeof t === 'string' && t.startsWith('context:action:')).map(t => t.slice(15));
     // Unknown actions conservatively activate every conditional restriction.
@@ -59,6 +78,7 @@ export function selectRules(nodes, { actions = [], projectRoot = process.cwd(),
   });
   return applicable.filter(node => !applicable.some(other => other !== node && other.subject && other.subject === node.subject &&
     other.supersedes?.includes(node.slug))).sort((a, b) =>
+    (rulePrecedence(b.slug) - rulePrecedence(a.slug)) ||
     Number(b.priority === 'absolute') - Number(a.priority === 'absolute') || (b.importance || 3) - (a.importance || 3) || String(a.slug).localeCompare(String(b.slug)));
 }
 

package/src/core/duplicate-guard.mjs

@@ -0,0 +1,350 @@
+/**
+ * Hermes-Grade Fail-Closed Duplicate Memory Guard
+ *
+ * Implements pre-write semantic collision checking co-opted from Nous Hermes / Hindsight
+ * (_find_related_observations).
+ *
+ * Prevents agents from polluting the vault with duplicate rules or disguising
+ * rule-violation incidents by re-recording existing invariants.
+ *
+ * Invariant:
+ * If an active rule or invariant with high token similarity or vector semantic proximity
+ * already exists, the write MUST FAIL CLOSED (Exit Code 1) with ZERO disk bytes written.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getNodes } from './vault-cache.mjs';
+import { loadEmbeddingsIndex, cosineSimilarity } from './embeddings.mjs';
+import { logger } from './logger.mjs';
+
+const RULE_CATEGORIES = new Set(['invariants', 'anti-patterns', 'preferences', 'rules']);
+
+const STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'has', 'he',
+  'in', 'is', 'it', 'its', 'of', 'on', 'that', 'the', 'to', 'was', 'were',
+  'will', 'with', 'before', 'after', 'using', 'used', 'use', 'any', 'all',
+  'should', 'must', 'each', 'this', 'these', 'those', 'such', 'than', 'then'
+]);
+
+/**
+ * Normalize and stem a token to its canonical semantic root.
+ */
+export function stemToken(word) {
+  let w = word.toLowerCase();
+  // Strip trailing punctuation
+  w = w.replace(/[^a-z0-9_-]/g, '');
+  if (w.length <= 2) return w;
+
+  // Synonyms and domain stems
+  if (w === 'docs' || w === 'documentation') return 'doc';
+  if (w === 'apis' || w === 'api') return 'api';
+  if (w === 'models' || w === 'model') return 'model';
+  if (w === 'names' || w === 'strings' || w === 'string') return 'name';
+  if (w.startsWith('search')) return 'search';
+  if (w.startsWith('hardcod')) return 'hardcode';
+  if (w.startsWith('pretrain')) return 'pretrain';
+  if (w.startsWith('reli') || w.startsWith('rely')) return 'rely';
+  if (w.startsWith('specif')) return 'spec';
+  if (w.startsWith('push')) return 'push';
+  if (w.startsWith('commit')) return 'commit';
+  if (w.startsWith('verif')) return 'verify';
+  if (w.startsWith('check')) return 'check';
+
+  // Standard suffix stripping
+  if (w.endsWith('ing') && w.length > 5) return w.slice(0, -3);
+  if (w.endsWith('es') && w.length > 4) return w.slice(0, -2);
+  if (w.endsWith('s') && !w.endsWith('ss') && w.length > 3) return w.slice(0, -1);
+  if (w.endsWith('ed') && w.length > 4) return w.slice(0, -2);
+  if (w.endsWith('ly') && w.length > 4) return w.slice(0, -2);
+
+  return w;
+}
+
+/**
+ * Tokenize text into stemmed, stopword-filtered semantic tokens.
+ */
+export function tokenize(text) {
+  if (!text || typeof text !== 'string') return new Set();
+  const rawWords = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s_-]/g, ' ')
+    .split(/\s+/)
+    .filter((w) => w.length > 1 && !STOPWORDS.has(w));
+
+  const stems = new Set();
+  for (const word of rawWords) {
+    const s = stemToken(word);
+    if (s && !STOPWORDS.has(s)) {
+      stems.add(s);
+    }
+  }
+  return stems;
+}
+
+/**
+ * Compute Jaccard similarity between two token sets.
+ */
+export function jaccard(setA, setB) {
+  if (setA.size === 0 && setB.size === 0) return 1;
+  let intersection = 0;
+  for (const item of setA) {
+    if (setB.has(item)) intersection++;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Compute containment ratio (how much of candidate's core tokens exist in target).
+ */
+export function containment(candidateSet, targetSet) {
+  if (candidateSet.size === 0) return 0;
+  let matches = 0;
+  for (const token of candidateSet) {
+    if (targetSet.has(token)) matches++;
+  }
+  return matches / candidateSet.size;
+}
+
+/**
+ * Find the location of an existing slug in compiled instruction surfaces.
+ */
+export function findSurfaceLocation(existingSlug, projectRoot = process.cwd()) {
+  const homeDir = process.env.HOME || '';
+  const candidates = [
+    path.join(projectRoot, 'AGENTS.md'),
+    path.join(projectRoot, 'INSTRUCTIONS.md'),
+    path.join(projectRoot, 'CLAUDE.md'),
+    path.join(projectRoot, '.cursorrules'),
+    path.join(homeDir, '.agent', 'INSTRUCTIONS.md'),
+    path.join(homeDir, '.agent', 'AGENTS.md'),
+  ];
+
+  for (const candidatePath of candidates) {
+    if (fs.existsSync(candidatePath)) {
+      try {
+        const content = fs.readFileSync(candidatePath, 'utf8');
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes(existingSlug)) {
+            return {
+              file: path.basename(candidatePath),
+              path: candidatePath,
+              line: i + 1,
+              snippet: lines[i].trim().slice(0, 100),
+            };
+          }
+        }
+      } catch {
+        // Ignore read errors
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Record a rule violation incident into the persistent incidents log.
+ */
+export function logIncident(incident, derivedDir) {
+  try {
+    fs.mkdirSync(derivedDir, { recursive: true });
+    const logPath = path.join(derivedDir, 'incidents.jsonl');
+    fs.appendFileSync(logPath, JSON.stringify(incident) + '\n', 'utf8');
+  } catch (err) {
+    logger.warn('duplicate-guard', `Failed to record incident to ${derivedDir}: ${err.message}`);
+  }
+}
+
+/**
+ * Check if a candidate rule/invariant node is a duplicate of an existing active node.
+ *
+ * @param {object} candidate - The candidate node to be remembered.
+ * @param {object} options
+ * @param {string} options.vaultDir - Path to current vault directory.
+ * @param {string} [options.derivedDir] - Path to memory-derived directory.
+ * @param {string} [options.globalVaultDir] - Global vault, as resolved by the caller's brain owner. Also searched when it differs from vaultDir.
+ * @param {string} [options.projectRoot] - Repository root directory.
+ * @param {number} [options.jaccardThreshold=0.45] - Threshold for token overlap.
+ * @param {number} [options.containmentThreshold=0.60] - Threshold for candidate containment.
+ * @param {number} [options.cosineThreshold=0.82] - Threshold for embedding cosine similarity.
+ * @returns {object} { isDuplicate: boolean, matchedNode?: object, similarity?: number, surfaceLoc?: object }
+ */
+export function checkDuplicateRule(candidate, options = {}) {
+  const {
+    vaultDir,
+    derivedDir,
+    globalVaultDir,
+    projectRoot = process.cwd(),
+    jaccardThreshold = 0.45,
+    containmentThreshold = 0.60,
+    cosineThreshold = 0.82,
+  } = options;
+
+  if (!candidate || !RULE_CATEGORIES.has(candidate.category)) {
+    return { isDuplicate: false };
+  }
+
+  // Load existing active nodes from the target vault
+  const vaultNodes = getNodes(vaultDir).filter(
+    (n) => n.status === 'active' && RULE_CATEGORIES.has(n.category) && n.slug !== candidate.slug
+  );
+
+  // If in a project brain, also check global vault to prevent duplicating global invariants
+  let allNodes = [...vaultNodes];
+  if (globalVaultDir && vaultDir !== globalVaultDir && fs.existsSync(globalVaultDir)) {
+    try {
+      const globalNodes = getNodes(globalVaultDir).filter(
+        (n) => n.status === 'active' && RULE_CATEGORIES.has(n.category) && n.slug !== candidate.slug
+      );
+      allNodes = [...allNodes, ...globalNodes];
+    } catch {
+      // Ignore global load errors if any
+    }
+  }
+
+  if (allNodes.length === 0) {
+    return { isDuplicate: false };
+  }
+
+  const candidateBody = (candidate.body || '').trim();
+  const candidateNorm = candidateBody.toLowerCase().replace(/\s+/g, ' ');
+  const candidateTokens = tokenize(
+    `${candidate.title || ''} ${candidateBody} ${candidate.subject || ''} ${candidate.predicate || ''} ${candidate.object || ''}`
+  );
+
+  // Optional vector index check
+  let embeddingsIndex = null;
+  if (derivedDir && fs.existsSync(path.join(derivedDir, 'embeddings.db'))) {
+    try {
+      embeddingsIndex = loadEmbeddingsIndex(derivedDir);
+    } catch {
+      embeddingsIndex = null;
+    }
+  }
+
+  for (const existing of allNodes) {
+    const existingBody = (existing.body || '').trim();
+    const existingNorm = existingBody.toLowerCase().replace(/\s+/g, ' ');
+
+    // 1. Exact or near-exact normalized body match
+    if (candidateNorm.length > 10 && (candidateNorm === existingNorm || existingNorm.includes(candidateNorm) || candidateNorm.includes(existingNorm))) {
+      const surfaceLoc = findSurfaceLocation(existing.slug, projectRoot);
+      return {
+        isDuplicate: true,
+        matchedNode: existing,
+        similarity: 1.0,
+        surfaceLoc,
+      };
+    }
+
+    // 2. Token Jaccard similarity & Containment
+    const existingTokens = tokenize(
+      `${existing.title || ''} ${existingBody} ${existing.subject || ''} ${existing.predicate || ''} ${existing.object || ''}`
+    );
+    const tokenSim = jaccard(candidateTokens, existingTokens);
+    const containSim = containment(candidateTokens, existingTokens);
+
+    if (tokenSim >= jaccardThreshold || containSim >= containmentThreshold) {
+      const surfaceLoc = findSurfaceLocation(existing.slug, projectRoot);
+      const effectiveSim = Math.max(tokenSim, containSim);
+      return {
+        isDuplicate: true,
+        matchedNode: existing,
+        similarity: Math.round(effectiveSim * 1000) / 1000,
+        surfaceLoc,
+      };
+    }
+
+    // 3. Vector Embedding similarity (if available)
+    if (embeddingsIndex && embeddingsIndex[candidate.slug] && embeddingsIndex[existing.slug]) {
+      try {
+        const vecSim = cosineSimilarity(
+          embeddingsIndex[candidate.slug].embedding,
+          embeddingsIndex[existing.slug].embedding
+        );
+        if (vecSim >= cosineThreshold) {
+          const surfaceLoc = findSurfaceLocation(existing.slug, projectRoot);
+          return {
+            isDuplicate: true,
+            matchedNode: existing,
+            similarity: Math.round(vecSim * 1000) / 1000,
+            surfaceLoc,
+          };
+        }
+      } catch {
+        // Fall back to token match
+      }
+    }
+  }
+
+  return { isDuplicate: false };
+}
+
+/**
+ * Enforces that a candidate rule is not a duplicate.
+ * Throws an Error and logs an incident if a collision occurs.
+ */
+export function assertNoDuplicateRule(candidate, options = {}) {
+  const check = checkDuplicateRule(candidate, options);
+  if (!check.isDuplicate) return;
+
+  const { matchedNode, similarity, surfaceLoc } = check;
+  const surfaceStr = surfaceLoc ? `${surfaceLoc.file} at Line ${surfaceLoc.line}` : 'Active Invariant Pool';
+
+  const incident = {
+    timestamp: new Date().toISOString(),
+    session_id: process.env.TR_SESSION_ID || 'unknown',
+    event: 'rule_write_rejected',
+    reason: 'An attempt was made to write a rule that already exists in active memory.',
+    attempted: {
+      category: candidate.category,
+      title: candidate.title,
+      body: candidate.body,
+      priority: candidate.priority || 'normal',
+    },
+    existing: {
+      slug: matchedNode.slug,
+      title: matchedNode.title,
+      body: matchedNode.body,
+      priority: matchedNode.priority || 'normal',
+      category: matchedNode.category,
+    },
+    similarity,
+    surface_location: surfaceStr,
+  };
+
+  if (options.derivedDir) {
+    logIncident(incident, options.derivedDir);
+  }
+
+  const message = [
+    '',
+    '================================================================================',
+    '🚨 VIOLATION INCIDENT DETECTED: DUPLICATE RULE REJECTED',
+    '--------------------------------------------------------------------------------',
+    `Attempted Rule: "${candidate.body}"`,
+    `Existing Rule:  [${matchedNode.slug}] "${matchedNode.body}"`,
+    `Similarity:     ${Math.round(similarity * 100)}%`,
+    `Surface Status: Active (${surfaceStr})`,
+    '',
+    'ROOT-CAUSE ANALYSIS:',
+    'The agent attempted to write a rule that ALREADY exists in the active instruction',
+    'surface. This indicates the agent failed to follow an invariant that was already',
+    'active in its context.',
+    '',
+    'Refusing to write duplicate node. Zero disk bytes written.',
+    'Fix the agent\'s behavior at the source.',
+    '================================================================================',
+    '',
+  ].join('\n');
+
+  console.error(message);
+
+  const error = new Error(`Rule already exists: [${matchedNode.slug}] "${matchedNode.body}" (${Math.round(similarity * 100)}% match)`);
+  error.code = 'ERR_DUPLICATE_RULE';
+  error.incident = incident;
+  error.matchedNode = matchedNode;
+  throw error;
+}