mindforge-cc 11.0.0 → 11.2.1

package/bin/memory/vector-hub.js

@@ -23,6 +23,30 @@ class VectorHub {
     this.initialized = false;
     this._writeCount = 0;
     this._batchSize = 10;
+    // UC-09: serialized async persistence chain. Successive save() calls queue
+    // behind one another so two exports never write the .db file concurrently
+    // (a corrupted half-written database would otherwise be possible).
+    this._saveChain = Promise.resolve();
+    // Count of async save()s that have been SCHEDULED but not yet COMPLETED their
+    // durable disk write. A boolean here is unsafe: with two rapid saves the chain
+    // is [writeA → clear → writeB → clear], leaving a window where the flag reads
+    // "clean" while writeB is still pending — a hard process.exit() in that window
+    // would make the exit guard skip saveSync() and lose the last batch (the exact
+    // data loss this guard exists to prevent). A counter has no such gap: it only
+    // returns to 0 once EVERY scheduled save has completed. saveSync() always
+    // exports the current in-memory DB, so over-flushing on exit is harmless — we
+    // deliberately bias toward flushing.
+    this._pendingSaves = 0;
+    this._exitGuardInstalled = false;
+  }
+
+  _installExitGuard() {
+    if (this._exitGuardInstalled) return;
+    this._exitGuardInstalled = true;
+    // 'exit' handlers can only run synchronous code — saveSync() fits exactly.
+    process.once('exit', () => {
+      if (this._db && this._pendingSaves > 0) this.saveSync();
+    });
   }
 
   _ensureDir() {
@@ -32,6 +56,26 @@ class VectorHub {
     }
   }
 
+  /**
+   * Idempotently add a column to an existing table (lightweight migration).
+   * SQLite has no "ADD COLUMN IF NOT EXISTS", so we run the ALTER and swallow
+   * only the "duplicate column name" error — which simply means the column is
+   * already present (the table was created with it, or a prior run added it).
+   * Any other error is re-thrown so genuine schema problems surface loudly.
+   * @param {string} table
+   * @param {string} column
+   * @param {string} typeDecl - e.g. 'TEXT', 'INTEGER DEFAULT 0'
+   */
+  _addColumnIfMissing(table, column, typeDecl) {
+    try {
+      this._db.run(`ALTER TABLE ${table} ADD COLUMN ${column} ${typeDecl}`);
+    } catch (err) {
+      if (!/duplicate column name/i.test(err && err.message)) {
+        throw err;
+      }
+    }
+  }
+
   /**
    * Initialize the WASM SQLite database and create tables + indexes.
    */
@@ -100,11 +144,23 @@ class VectorHub {
         id TEXT PRIMARY KEY,
         request_id TEXT NOT NULL,
         status TEXT NOT NULL,
+        did TEXT,
+        signed_message TEXT,
         attestation_payload TEXT,
         timestamp TEXT NOT NULL
       )
     `);
 
+    // UC-22 (audit finding #2): orbital attestations must carry the signer DID
+    // and the EXACT canonical message that was signed so verify() can re-check
+    // the cryptographic signature instead of trusting status='APPROVED' alone.
+    // CREATE TABLE IF NOT EXISTS won't add columns to a database created before
+    // this fix, so back-fill them with guarded ALTER TABLE statements. SQLite
+    // throws "duplicate column name" when the column already exists — that case
+    // is the success path (already migrated), so it is swallowed.
+    this._addColumnIfMissing('attestations', 'did', 'TEXT');
+    this._addColumnIfMissing('attestations', 'signed_message', 'TEXT');
+
     this._db.run(`
       CREATE TABLE IF NOT EXISTS mesh_config (
         key TEXT PRIMARY KEY,
@@ -167,22 +223,74 @@ class VectorHub {
     this._db.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_migrations_name ON _migrations(name)');
 
     this.initialized = true;
+    this._installExitGuard();
     this.save();
     console.log(`[VectorHub] Initialized WASM SQLite persistence at ${this.dbPath}`);
   }
 
   /**
-   * Persist the in-memory database to disk.
+   * Persist the in-memory database to disk (UC-09).
+   *
+   * sql.js export() is intrinsically synchronous, but the (potentially large)
+   * FILE WRITE no longer blocks the event loop: we snapshot the bytes
+   * synchronously, then write+fsync them asynchronously. Successive saves are
+   * serialized on a single chain so two exports never write the .db file
+   * concurrently. The write is crash-safe (tmp file + atomic rename + fsync),
+   * so a partial write can never leave a corrupted database on disk.
+   *
+   * @returns {Promise<void>} Resolves once the snapshot is durably on disk.
    */
   save() {
+    if (!this._db) return Promise.resolve();
+
+    let buffer;
+    try {
+      this._ensureDir();
+      // Snapshot the DB synchronously so the bytes reflect this exact moment.
+      buffer = Buffer.from(this._db.export());
+    } catch (err) {
+      console.warn(`[VectorHub] Failed to export database: ${err.message}`);
+      return Promise.resolve();
+    }
+
+    const dbPath = this.dbPath;
+    // Increment when SCHEDULED; decrement only once this specific save has
+    // COMPLETED (success or failure). The exit guard fires saveSync() while any
+    // scheduled save is still outstanding — see _installExitGuard().
+    this._pendingSaves++;
+    this._saveChain = this._saveChain.then(() => writeDbDurable(dbPath, buffer))
+      .catch((err) => {
+        console.warn(`[VectorHub] Failed to save database: ${err.message}`);
+      })
+      .then(() => { this._pendingSaves--; });
+    return this._saveChain;
+  }
+
+  /**
+   * Synchronous, crash-safe persistence — used only on shutdown to GUARANTEE
+   * no acknowledged write is lost if the process exits before the async save
+   * chain drains. Correctness over non-blocking here.
+   */
+  saveSync() {
     if (!this._db) return;
     try {
       this._ensureDir();
-      const data = this._db.export();
-      const buffer = Buffer.from(data);
-      fs.writeFileSync(this.dbPath, buffer);
+      const buffer = Buffer.from(this._db.export());
+      const tmpPath = `${this.dbPath}.tmp.${process.pid}`;
+      const fd = fs.openSync(tmpPath, 'w');
+      try {
+        fs.writeSync(fd, buffer);
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+      fs.renameSync(tmpPath, this.dbPath);
+      // A sync export captures the full in-memory DB — a superset of anything the
+      // outstanding async saves would have written — so the pending work is now
+      // durably satisfied. Clearing the counter prevents a redundant second flush.
+      this._pendingSaves = 0;
     } catch (err) {
-      console.warn(`[VectorHub] Failed to save database: ${err.message}`);
+      console.warn(`[VectorHub] Failed to save database (sync): ${err.message}`);
     }
   }
 
@@ -199,10 +307,13 @@ class VectorHub {
 
   /**
    * Close the database and save final state to disk.
+   * Drains any pending async saves, then performs a guaranteed synchronous
+   * durable write so no acknowledged data is lost on shutdown (UC-09).
    */
   async close() {
     if (this._db) {
-      this.save();
+      try { await this._saveChain; } catch { /* logged in save() */ }
+      this.saveSync();
       this._db.close();
       this._db = null;
       this.initialized = false;
@@ -455,6 +566,32 @@ class VectorHub {
   }
 }
 
+// ── Durable async DB file write (UC-09) ───────────────────────────────────────
+// Crash-safe: write to a tmp file, fsync, then atomically rename over the target.
+// A crash mid-write leaves the previous good .db intact (rename is atomic on POSIX).
+function writeDbDurable(dbPath, buffer) {
+  return new Promise((resolve, reject) => {
+    const tmpPath = `${dbPath}.tmp.${process.pid}`;
+    const fail = (err) => { fs.unlink(tmpPath, () => reject(err)); };
+    fs.open(tmpPath, 'w', (openErr, fd) => {
+      if (openErr) return reject(openErr);
+      fs.write(fd, buffer, 0, buffer.length, 0, (writeErr) => {
+        if (writeErr) { fs.close(fd, () => fail(writeErr)); return; }
+        fs.fsync(fd, (syncErr) => {
+          fs.close(fd, (closeErr) => {
+            if (syncErr) return fail(syncErr);
+            if (closeErr) return fail(closeErr);
+            fs.rename(tmpPath, dbPath, (renameErr) => {
+              if (renameErr) return fail(renameErr);
+              resolve();
+            });
+          });
+        });
+      });
+    });
+  });
+}
+
 // ── Factory Function ──────────────────────────────────────────────────────────
 
 /**

package/bin/mindforge-cli.js

@@ -115,11 +115,6 @@ const COMMANDS = {
     script: 'bin/autonomous/mesh-self-healer.js',
     description: 'Auto-detect and repair reasoning drifts in the active swarm'
   },
-  'quantum-verify': {
-    script: 'bin/governance/quantum-crypto.js',
-    description: 'Verify framework integrity using post-quantum signatures',
-    defaultArgs: ['--verify', '.mindforge/engine/']
-  },
   // Planned: jira-sync, confluence-sync (not yet implemented)
   'metrics': {
     script: 'bin/dashboard/metrics-aggregator.js',
@@ -138,6 +133,10 @@ const COMMANDS = {
     script: 'bin/engine/learning-manager.js',
     description: 'Append a new Learning Entry to the Evolution Log',
     defaultArgs: ['record']
+  },
+  'verify': {
+    script: 'bin/engine/verify-cli.js',
+    description: 'Run unified verification (tests, lint, audit, typecheck) and write report'
   }
 };
 

package/bin/models/anthropic-provider.js

@@ -15,7 +15,7 @@ class AnthropicProvider {
 
     const data = JSON.stringify({
       model,
-      system: systemPrompt,
+      system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
       messages: [{ role: 'user', content: userMessage }],
       max_tokens: maxTokens,
       temperature,
@@ -45,15 +45,24 @@ class AnthropicProvider {
 
             const inputTokens = json.usage.input_tokens;
             const outputTokens = json.usage.output_tokens;
-            
-            // Basic cost calculation (Sonnet 3.5 prices)
-            const cost = (inputTokens * 0.000003) + (outputTokens * 0.000015);
+            const cacheRead = json.usage.cache_read_input_tokens || 0;
+            const cacheCreate = json.usage.cache_creation_input_tokens || 0;
+
+            const { priceCall } = require('./pricing-registry');
+            const cost = priceCall(json.model, {
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+              cache_read_input_tokens: cacheRead,
+              cache_creation_input_tokens: cacheCreate,
+            });
 
             resolve({
               model: json.model,
               content: json.content[0].text,
               input_tokens: inputTokens,
               output_tokens: outputTokens,
+              cache_read_input_tokens: cacheRead,
+              cache_creation_input_tokens: cacheCreate,
               cost_usd: cost,
               provider: 'anthropic'
             });

package/bin/models/cost-tracker.js

@@ -101,10 +101,12 @@ function getSummary(params = { days: 7 }) {
         result.calls++;
         
         const model = entry.model || 'unknown';
-        if (!result.by_model[model]) result.by_model[model] = { cost: 0, calls: 0, tokens: 0 };
+        if (!result.by_model[model]) result.by_model[model] = { cost: 0, calls: 0, tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 };
         result.by_model[model].cost += cost;
         result.by_model[model].calls++;
         result.by_model[model].tokens += (entry.input_tokens || 0) + (entry.output_tokens || 0);
+        result.by_model[model].cache_read_tokens += (entry.cache_read_input_tokens || 0);
+        result.by_model[model].cache_creation_tokens += (entry.cache_creation_input_tokens || 0);
 
         const phase = entry.phase || 'unknown';
         if (!result.by_phase[phase]) result.by_phase[phase] = 0;

package/bin/models/difficulty-scorer.js

@@ -0,0 +1,54 @@
+'use strict';
+/**
+ * MindForge — Difficulty Scorer (UC-06). Pure heuristic 1-10.
+ * Used by model-router in SHADOW MODE to log intended routing
+ * without altering actual model selection.
+ */
+
+const HIGH_KW = /auth|jwt|oauth|crypto|security|payment|pii|gdpr|hipaa|encrypt|secret|credential/i;
+const MED_KW = /refactor|migrate|architect|design|performance|concurrency|async/i;
+
+/**
+ * Score a task for difficulty on a 1-10 scale.
+ * @param {object} task
+ * @param {string} [task.description] — free-text task description
+ * @param {string[]} [task.files] — files involved
+ * @param {number} [task.tier] — security tier (1-3)
+ * @returns {number} integer difficulty score in [1, 10]
+ */
+function score(task = {}) {
+  const desc = task.description || '';
+  const files = task.files || [];
+  const tier = task.tier || 0;
+
+  let s = 3; // baseline
+
+  // Keyword analysis (description + file paths)
+  if (HIGH_KW.test(desc) || files.some(f => HIGH_KW.test(f))) {
+    s += 4;
+  } else if (MED_KW.test(desc)) {
+    s += 2;
+  }
+
+  // File count complexity
+  if (files.length > 10) {
+    s += 2;
+  } else if (files.length > 5) {
+    s += 1;
+  }
+
+  // Long description signals complexity
+  if (desc.length > 500) {
+    s += 1;
+  }
+
+  // Tier-3 floor: security/privacy tasks never score below 7
+  if (tier >= 3) {
+    s = Math.max(s, 7);
+  }
+
+  // Clamp to [1, 10]
+  return Math.min(Math.max(s, 1), 10);
+}
+
+module.exports = { score };

package/bin/models/gemini-provider.js

@@ -46,10 +46,14 @@ class GeminiProvider {
               return reject(Object.assign(new Error(json.error?.message || 'Gemini API error'), { status: res.statusCode }));
             }
 
-            // Gemini 1.5 Pro billing is complex; using $1.25 / 1M input as baseline
             const inputTokens = json.usageMetadata.promptTokenCount;
             const outputTokens = json.usageMetadata.candidatesTokenCount;
-            const cost = (inputTokens * 0.00000125) + (outputTokens * 0.00000375);
+
+            const { priceCall } = require('./pricing-registry');
+            const cost = priceCall(modelId, {
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+            });
 
             resolve({
               model: modelId,

package/bin/models/model-router.js

@@ -74,46 +74,59 @@ function readMindforgeSettings() {
   return _settingsCache;
 }
 
-function route(persona = 'developer', tier = 1) {
+function route(persona = 'developer', tier = 1, taskContext) {
   const settings = readMindforgeSettings();
-  
+  let result;
+
   // 1. Tier 3 override (Security/Privacy always uses SECURITY_MODEL)
   if (tier === 3) {
-    return {
+    result = {
       model: settings.SECURITY_MODEL,
       setting: 'SECURITY_MODEL',
       reason: 'Tier 3 (Security/Privacy) override'
     };
   }
-
   // 2. Persona mapping (Specific personas like research, debug, qa)
-  if (persona !== 'developer' && PERSONA_MAP[persona]) {
+  else if (persona !== 'developer' && PERSONA_MAP[persona]) {
     const settingKey = PERSONA_MAP[persona];
-    return {
+    result = {
       model: settings[settingKey],
       setting: settingKey,
       reason: `Mapped from specific persona "${persona}"`
     };
   }
-
   // 3. Budget Bias (Tier 1 uses QUICK_MODEL for default developer tasks)
-  if (tier === 1) {
-    return {
+  else if (tier === 1) {
+    result = {
       model: settings.QUICK_MODEL,
       setting: 'QUICK_MODEL',
       reason: 'Tier 1 Budget Bias (efficiency mode)'
     };
   }
-
   // 4. Default mapping
-  const settingKey = 'EXECUTOR_MODEL';
-  const model = settings[settingKey];
-
-  return {
-    model,
-    setting: settingKey,
-    reason: `Default EXECUTOR_MODEL for tier ${tier}`
-  };
+  else {
+    const settingKey = 'EXECUTOR_MODEL';
+    result = {
+      model: settings[settingKey],
+      setting: settingKey,
+      reason: `Default EXECUTOR_MODEL for tier ${tier}`
+    };
+  }
+
+  // Shadow-mode: difficulty-aware routing (UC-06)
+  // Logs what model the difficulty scorer WOULD select, without changing the result.
+  if (taskContext) {
+    const { score: scoreDifficulty } = require('./difficulty-scorer');
+    const difficulty = scoreDifficulty(taskContext);
+    const shadowModel = difficulty <= 3 ? settings.QUICK_MODEL
+                      : difficulty >= 8 ? settings.PLANNER_MODEL
+                      : settings.EXECUTOR_MODEL;
+    if (shadowModel !== result.model) {
+      process.stderr.write(`[model-router:shadow] difficulty=${difficulty} would route to ${shadowModel} (actual: ${result.model})\n`);
+    }
+  }
+
+  return result;
 }
 
 function getModel(settingKey) {

package/bin/models/openai-provider.js

@@ -46,9 +46,12 @@ class OpenAIProvider {
 
             const inputTokens = json.usage.prompt_tokens;
             const outputTokens = json.usage.completion_tokens;
-            
-            // Basic cost calculation (GPT-4o prices)
-            const cost = (inputTokens * 0.000005) + (outputTokens * 0.000015);
+
+            const { priceCall } = require('./pricing-registry');
+            const cost = priceCall(json.model, {
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+            });
 
             resolve({
               model: json.model,

package/bin/models/pricing-registry.js

@@ -0,0 +1,128 @@
+/**
+ * MindForge v2 — Pricing Registry (UC-05)
+ *
+ * Single source of truth for all model pricing. Loads from
+ * .mindforge/config.json `revops.market_registry` and normalizes
+ * to per-1M-token units. All providers and cost-tracker MUST
+ * query this module instead of hardcoding rates.
+ *
+ * Buckets: input, output, cache_read, cache_creation
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_PATH = path.join(__dirname, '..', '..', '.mindforge', 'config.json');
+
+// Fallback per-1M rates when model is unknown (generous estimate to avoid under-billing)
+const FALLBACK_RATES = {
+  input: 5.0,
+  output: 15.0,
+  cache_read: 0.5,
+  cache_creation: 6.25,
+};
+
+let _priceTable = null;
+
+/**
+ * Load and normalize the market_registry from config.json.
+ * Config values are in per-1K-token units. We multiply by 1000 to get per-1M.
+ * Cache buckets: cache_read = 10% of input, cache_creation = 125% of input
+ * (unless explicitly provided in config).
+ */
+function loadPriceTable() {
+  const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+  const config = JSON.parse(raw);
+  const registry = config.revops && config.revops.market_registry;
+
+  if (!registry || typeof registry !== 'object') {
+    process.stderr.write('[pricing-registry] WARN: market_registry missing from config.json, using fallbacks\n');
+    return {};
+  }
+
+  const table = {};
+  for (const [modelId, entry] of Object.entries(registry)) {
+    const inputPer1M = (entry.cost_input || 0) * 1000;
+    const outputPer1M = (entry.cost_output || 0) * 1000;
+
+    // Cache bucket derivation: use explicit config fields if present,
+    // otherwise derive from Anthropic-standard ratios
+    const cacheReadPer1M = entry.cost_cache_read != null
+      ? entry.cost_cache_read * 1000
+      : inputPer1M * 0.1;
+    const cacheCreationPer1M = entry.cost_cache_creation != null
+      ? entry.cost_cache_creation * 1000
+      : inputPer1M * 1.25;
+
+    table[modelId] = {
+      input: inputPer1M,
+      output: outputPer1M,
+      cache_read: cacheReadPer1M,
+      cache_creation: cacheCreationPer1M,
+    };
+  }
+  return table;
+}
+
+function ensureLoaded() {
+  if (_priceTable === null) {
+    _priceTable = loadPriceTable();
+  }
+  return _priceTable;
+}
+
+/**
+ * Get the per-1M-token price for a model+bucket.
+ * @param {string} modelId - e.g. 'claude-sonnet-4-6'
+ * @param {'input'|'output'|'cache_read'|'cache_creation'} bucket
+ * @returns {number} USD per 1M tokens
+ */
+function getPrice(modelId, bucket) {
+  const table = ensureLoaded();
+  const entry = table[modelId];
+  if (!entry) {
+    process.stderr.write(`[pricing-registry] WARN: unknown model "${modelId}", using fallback rates\n`);
+    return FALLBACK_RATES[bucket] || FALLBACK_RATES.input;
+  }
+  return entry[bucket] != null ? entry[bucket] : (FALLBACK_RATES[bucket] || 0);
+}
+
+/**
+ * Calculate total cost for a single API call.
+ * @param {string} modelId
+ * @param {object} usage
+ * @param {number} usage.input_tokens
+ * @param {number} usage.output_tokens
+ * @param {number} [usage.cache_read_input_tokens=0]
+ * @param {number} [usage.cache_creation_input_tokens=0]
+ * @returns {number} Total USD cost
+ */
+function priceCall(modelId, usage) {
+  const inputTokens = usage.input_tokens || 0;
+  const outputTokens = usage.output_tokens || 0;
+  const cacheReadTokens = usage.cache_read_input_tokens || 0;
+  const cacheCreationTokens = usage.cache_creation_input_tokens || 0;
+
+  const inputRate = getPrice(modelId, 'input');
+  const outputRate = getPrice(modelId, 'output');
+  const cacheReadRate = getPrice(modelId, 'cache_read');
+  const cacheCreationRate = getPrice(modelId, 'cache_creation');
+
+  const cost =
+    (inputTokens / 1_000_000) * inputRate +
+    (outputTokens / 1_000_000) * outputRate +
+    (cacheReadTokens / 1_000_000) * cacheReadRate +
+    (cacheCreationTokens / 1_000_000) * cacheCreationRate;
+
+  return cost;
+}
+
+/**
+ * Clear the cached price table (for testing or config reload).
+ */
+function clearCache() {
+  _priceTable = null;
+}
+
+module.exports = { getPrice, priceCall, clearCache };

package/bin/review/ads-engine.js

@@ -49,7 +49,7 @@ Include a [ADS_METRICS] block for your counter-proposal or critique logic.`,
     sessionId,
     phaseNum
   });
-  const redCritique = redResponse.content;
+  let redCritique = redResponse.content;
   process.stdout.write('done.\n');
 
   // Red-Team Jailbreak: Force higher-fidelity critiques if Auditor is too lenient

package/bin/review/finding-synthesizer.js

@@ -6,6 +6,10 @@
 
 const SEVERITY_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
 
+// A severity spread of this many levels (or more) within a single location-group
+// is treated as a contradiction (e.g. CRITICAL=3 vs LOW=0 → gap 3).
+const CONTRADICTION_GAP_THRESHOLD = 2;
+
 function synthesizeFindings(reviews) {
   const allFindings = [];
   const modelSpecific = {};
@@ -18,8 +22,9 @@ function synthesizeFindings(reviews) {
     }
   }
 
-  // Detect consensus
+  // Detect consensus and contradictions from the same location-groups.
   const consensus = [];
+  const contradictions = [];
   const processed = new Set();
 
   for (let i = 0; i < allFindings.length; i++) {
@@ -31,7 +36,7 @@ function synthesizeFindings(reviews) {
     for (let j = i + 1; j < allFindings.length; j++) {
       if (processed.has(j)) continue;
       const f2 = allFindings[j];
-      
+
       if (isSameFinding(f1, f2)) {
         group.push(f2);
         processed.add(j);
@@ -45,13 +50,12 @@ function synthesizeFindings(reviews) {
         severity: getHighestSeverity(group.map(f => f.severity)),
         models: group.map(f => f.model),
       });
+
+      const contradiction = detectContradiction(f1.location, group);
+      if (contradiction) contradictions.push(contradiction);
     }
   }
 
-  // Detect contradictions (large severity gap on same finding)
-  const contradictions = [];
-  // (In a real implementation, we'd more deeply analyze conflicting logic)
-
   return {
     consensus,
     model_specific: modelSpecific,
@@ -92,6 +96,31 @@ function normalizeLocation(loc) {
   });
 }
 
+function severityRank(severity) {
+  const idx = SEVERITY_ORDER.indexOf(severity);
+  return idx < 0 ? 0 : idx;
+}
+
+// A location-group is contradictory when its reviews disagree on severity by
+// CONTRADICTION_GAP_THRESHOLD levels or more (e.g. CRITICAL vs LOW). Reuses the
+// already-computed location-group rather than re-deriving it.
+function detectContradiction(location, group) {
+  const ranks = group.map(f => severityRank(f.severity));
+  const maxRank = Math.max(...ranks);
+  const minRank = Math.min(...ranks);
+
+  if (maxRank - minRank < CONTRADICTION_GAP_THRESHOLD) return null;
+
+  return {
+    location,
+    severities: group.map(f => f.severity),
+    models: group.map(f => f.model),
+    description: `Severity disagreement at ${location}: ` +
+      `${SEVERITY_ORDER[minRank]} vs ${SEVERITY_ORDER[maxRank]} ` +
+      `(${maxRank - minRank}-level gap across ${group.length} reviews)`,
+  };
+}
+
 function getHighestSeverity(severities) {
   let highest = 0;
   for (const s of severities) {