@nerviq/cli 1.10.0 → 1.12.0

package/bin/cli.js

@@ -14,8 +14,9 @@ const { auditWorkspaces } = require('../src/workspace');
 const { scanOrg } = require('../src/org');
 const { detectAntiPatterns, printAntiPatterns, printAntiPatternCatalog } = require('../src/anti-patterns');
 const { VERIFICATION_DATES, getVerificationDate, getVerificationStats } = require('../src/verification-metadata');
-const { init: initI18n, t } = require('../src/i18n');
-const { version } = require('../package.json');
+const { init: initI18n, t } = require('../src/i18n');
+const { version } = require('../package.json');
+const { SNAPSHOT_MILESTONES } = require('../src/activity');
 
 const args = process.argv.slice(2);
 const COMMAND_ALIASES = {
@@ -28,7 +29,7 @@ const COMMAND_ALIASES = {
   gov: 'governance',
   outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'init', 'augment', 'suggest-only', 'plan', 'apply', 'fix', 'rollback', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'check-health', 'dashboard', 'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise', 'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export', 'freshness', 'suggest-rules', 'profile', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'init', 'augment', 'suggest-only', 'plan', 'apply', 'fix', 'rollback', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'check-health', 'dashboard', 'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise', 'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export', 'freshness', 'suggest-rules', 'profile', 'baseline', 'exception', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -47,7 +48,7 @@ function levenshtein(a, b) {
   return matrix[a.length][b.length];
 }
 
-function suggestCommand(input) {
+function suggestCommand(input) {
   const candidates = [...KNOWN_COMMANDS, ...Object.keys(COMMAND_ALIASES)];
   let best = null;
   let bestDistance = Infinity;
@@ -58,9 +59,30 @@ function suggestCommand(input) {
       bestDistance = distance;
     }
   }
-  return bestDistance <= 3 ? best : null;
-}
-
+  return bestDistance <= 3 ? best : null;
+}
+
+function parseNonNegativeIntegerFlag(value, flagName) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${flagName} requires a non-negative integer`);
+  }
+  return parsed;
+}
+
+function parseWebhookHeader(rawValue) {
+  const separator = rawValue.indexOf(':');
+  if (separator <= 0) {
+    throw new Error('--webhook-header requires NAME: VALUE');
+  }
+  const name = rawValue.slice(0, separator).trim();
+  const value = rawValue.slice(separator + 1).trim();
+  if (!name || !value) {
+    throw new Error('--webhook-header requires NAME: VALUE');
+  }
+  return { name, value };
+}
+
 function parseArgs(rawArgs) {
   const flags = [];
   let command = 'audit';
@@ -76,13 +98,27 @@ function parseArgs(rawArgs) {
   let feedbackEffect = null;
   let feedbackNotes = null;
   let feedbackSource = null;
-  let feedbackScoreDelta = null;
-  let platform = 'claude';
-  let format = null;
-  let port = null;
-  let workspace = null;
-  let webhookUrl = null;
-  let commandSet = false;
+  let feedbackScoreDelta = null;
+  let platform = 'claude';
+  let platformExplicit = false;
+  let format = null;
+  let port = null;
+  let workspace = null;
+  let webhookUrl = null;
+  let webhookHeaders = [];
+  let webhookRetries = null;
+  let snapshotTags = [];
+  let snapshotMilestone = null;
+  let campaigns = [];
+  let diffBase = null;
+  let diffHead = null;
+  let driftMode = null;
+  let exceptionOwner = null;
+  let exceptionReason = null;
+  let exceptionExpires = null;
+  let exceptionScope = null;
+  let exceptionClass = null;
+  let commandSet = false;
   let extraArgs = [];
   let convertFrom = null;
   let convertTo = null;
@@ -98,11 +134,11 @@ function parseArgs(rawArgs) {
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook' || arg === '--external' || arg === '--team-profile' || arg === '--lang') {
-      const value = rawArgs[i + 1];
-      if (!value || value.startsWith('--')) {
-        throw new Error(`${arg} requires a value`);
-      }
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port' || arg === '--workspace' || arg === '--check-version' || arg === '--webhook' || arg === '--webhook-header' || arg === '--webhook-retries' || arg === '--external' || arg === '--team-profile' || arg === '--lang' || arg === '--tag' || arg === '--milestone' || arg === '--campaign' || arg === '--diff-base' || arg === '--diff-head' || arg === '--drift-mode' || arg === '--owner' || arg === '--reason' || arg === '--expires' || arg === '--scope' || arg === '--class') {
+      const value = rawArgs[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} requires a value`);
+      }
       if (arg === '--threshold') threshold = value;
       if (arg === '--out') out = value;
       if (arg === '--plan') planFile = value;
@@ -116,20 +152,33 @@ function parseArgs(rawArgs) {
       if (arg === '--notes') feedbackNotes = value;
       if (arg === '--source') feedbackSource = value.trim();
       if (arg === '--score-delta') feedbackScoreDelta = value.trim();
-      if (arg === '--platform') platform = value.trim().toLowerCase();
+      if (arg === '--platform') { platform = value.trim().toLowerCase(); platformExplicit = true; }
       if (arg === '--format') format = value.trim().toLowerCase();
       if (arg === '--from') { convertFrom = value.trim(); migrateFrom = value.trim(); }
       if (arg === '--to') { convertTo = value.trim(); migrateTo = value.trim(); }
       if (arg === '--port') port = value.trim();
-      if (arg === '--workspace') workspace = value.trim();
-      if (arg === '--check-version') checkVersion = value.trim();
-      if (arg === '--webhook') webhookUrl = value.trim();
-      if (arg === '--external') external = value.trim();
-      if (arg === '--team-profile') teamProfile = value.trim();
-      if (arg === '--lang') lang = value.trim().toLowerCase();
-      i++;
-      continue;
-    }
+      if (arg === '--workspace') workspace = value.trim();
+      if (arg === '--check-version') checkVersion = value.trim();
+      if (arg === '--webhook') webhookUrl = value.trim();
+      if (arg === '--webhook-header') webhookHeaders.push(parseWebhookHeader(value));
+      if (arg === '--webhook-retries') webhookRetries = parseNonNegativeIntegerFlag(value.trim(), '--webhook-retries');
+      if (arg === '--external') external = value.trim();
+      if (arg === '--team-profile') teamProfile = value.trim();
+      if (arg === '--lang') lang = value.trim().toLowerCase();
+      if (arg === '--tag') snapshotTags.push(value.trim());
+      if (arg === '--milestone') snapshotMilestone = value.trim().toLowerCase();
+      if (arg === '--campaign') campaigns = value.split(',').map(item => item.trim()).filter(Boolean);
+      if (arg === '--diff-base') diffBase = value.trim();
+      if (arg === '--diff-head') diffHead = value.trim();
+      if (arg === '--drift-mode') driftMode = value.trim().toLowerCase();
+      if (arg === '--owner') exceptionOwner = value.trim();
+      if (arg === '--reason') exceptionReason = value;
+      if (arg === '--expires') exceptionExpires = value.trim();
+      if (arg === '--scope') exceptionScope = value.trim().toLowerCase();
+      if (arg === '--class') exceptionClass = value.trim().toLowerCase();
+      i++;
+      continue;
+    }
 
     if (arg.startsWith('--lang=')) {
       lang = arg.split('=').slice(1).join('=').trim().toLowerCase();
@@ -141,10 +190,65 @@ function parseArgs(rawArgs) {
       continue;
     }
 
-    if (arg.startsWith('--external=')) {
-      external = arg.split('=').slice(1).join('=').trim();
-      continue;
-    }
+    if (arg.startsWith('--external=')) {
+      external = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--tag=')) {
+      snapshotTags.push(arg.split('=').slice(1).join('=').trim());
+      continue;
+    }
+
+    if (arg.startsWith('--milestone=')) {
+      snapshotMilestone = arg.split('=').slice(1).join('=').trim().toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--campaign=')) {
+      campaigns = arg.split('=').slice(1).join('=').split(',').map(item => item.trim()).filter(Boolean);
+      continue;
+    }
+
+    if (arg.startsWith('--diff-base=')) {
+      diffBase = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--diff-head=')) {
+      diffHead = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--drift-mode=')) {
+      driftMode = arg.split('=').slice(1).join('=').trim().toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--owner=')) {
+      exceptionOwner = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--reason=')) {
+      exceptionReason = arg.split('=').slice(1).join('=');
+      continue;
+    }
+
+    if (arg.startsWith('--expires=')) {
+      exceptionExpires = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--scope=')) {
+      exceptionScope = arg.split('=').slice(1).join('=').trim().toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--class=')) {
+      exceptionClass = arg.split('=').slice(1).join('=').trim().toLowerCase();
+      continue;
+    }
 
     if (arg === '--repos') {
       // Collect all following non-flag args as repo paths (supports comma-separated too)
@@ -227,10 +331,11 @@ function parseArgs(rawArgs) {
       continue;
     }
 
-    if (arg.startsWith('--platform=')) {
-      platform = arg.split('=').slice(1).join('=').trim().toLowerCase();
-      continue;
-    }
+    if (arg.startsWith('--platform=')) {
+      platform = arg.split('=').slice(1).join('=').trim().toLowerCase();
+      platformExplicit = true;
+      continue;
+    }
 
     if (arg.startsWith('--format=')) {
       format = arg.split('=').slice(1).join('=').trim().toLowerCase();
@@ -247,14 +352,29 @@ function parseArgs(rawArgs) {
       continue;
     }
 
-    if (arg.startsWith('--check-version=')) {
-      checkVersion = arg.split('=').slice(1).join('=').trim();
-      continue;
-    }
-
-    if (arg.startsWith('--')) {
-      flags.push(arg);
-      continue;
+    if (arg.startsWith('--check-version=')) {
+      checkVersion = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--webhook=')) {
+      webhookUrl = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--webhook-header=')) {
+      webhookHeaders.push(parseWebhookHeader(arg.split('=').slice(1).join('=')));
+      continue;
+    }
+
+    if (arg.startsWith('--webhook-retries=')) {
+      webhookRetries = parseNonNegativeIntegerFlag(arg.split('=').slice(1).join('=').trim(), '--webhook-retries');
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      flags.push(arg);
+      continue;
     }
 
     if (!commandSet) {
@@ -268,7 +388,7 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, commandExplicit, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, external, repos, teamProfile, lang };
+  return { flags, command, commandExplicit, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, platformExplicit, format, port, workspace, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo, checkVersion, webhookUrl, webhookHeaders, webhookRetries, external, repos, teamProfile, lang, snapshotTags, snapshotMilestone, campaigns, diffBase, diffHead, driftMode, exceptionOwner, exceptionReason, exceptionExpires, exceptionScope, exceptionClass };
 }
 
 function printWorkspaceSummary(summary, options) {
@@ -291,30 +411,54 @@ function printWorkspaceSummary(summary, options) {
   }
   console.log(`  Root governance audit: \x1b[1m${rootScore}\x1b[0m`);
   console.log(`  Workspace audit average: \x1b[1m${workspaceAverage}/100\x1b[0m`);
+  if (summary.profileBreakdown?.length > 0) {
+    const profileLine = summary.profileBreakdown
+      .map((item) => `${item.profileLabel} (${item.workspaceCount})`)
+      .join(', ');
+    console.log(`  Workspace profiles: ${profileLine}`);
+  }
   console.log('  Score semantics: root governance shows shared repo policy health; workspace average shows package-level coverage across the selected workspaces.');
   console.log('  Aggregate vs package: per-workspace scores can legitimately trail the root repo score in a monorepo.');
+  console.log('  Stack-specific checks: Go, Python, Node, and other workspace types can have different applicable totals.');
   console.log('');
-  console.log('\x1b[1m  Workspace                  Audit  Pass  Total  Top action\x1b[0m');
-  console.log('  ' + '─'.repeat(72));
+  console.log('\x1b[1m  Workspace                  Profile              Audit  Pass  Total  Top action\x1b[0m');
+  console.log('  ' + '─'.repeat(96));
   for (const item of summary.workspaces) {
     const score = item.score === null ? 'ERR' : String(item.score);
-    const topAction = item.error || item.topAction || '-';
-    console.log(`  ${item.workspace.padEnd(26)} ${score.padStart(5)} ${String(item.passed).padStart(5)} ${String(item.total).padStart(6)}  ${topAction}`);
-  }
-  console.log('');
-}
-
-function printScanDetail(summary, options) {
-  if (options.json) {
-    console.log(JSON.stringify(summary, null, 2));
-    return;
+    const topAction = item.error || item.topAction || '-';
+    const profile = (item.workspaceProfile?.label || 'General workspace').slice(0, 20);
+    console.log(`  ${item.workspace.padEnd(26)} ${profile.padEnd(20)} ${score.padStart(5)} ${String(item.passed).padStart(5)} ${String(item.total).padStart(6)}  ${topAction}`);
+    if (item.stackLabels?.length > 0) {
+      console.log(`\x1b[2m     Stacks: ${item.stackLabels.join(', ')}\x1b[0m`);
+    }
+  }
+  console.log('');
+}
+
+function printCompareCheckSection(title, items, prefix) {
+  if (!Array.isArray(items) || items.length === 0) return;
+  console.log(`  ${title} (${items.length}):`);
+  for (const item of items) {
+    const impact = item.impact ? ` [${item.impact}]` : '';
+    const category = item.category ? ` — ${item.category}` : '';
+    console.log(`    ${prefix} ${item.key}${impact}: ${item.name}${category}`);
+  }
+}
+
+function printScanDetail(summary, options) {
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
   }
 
-  console.log('');
-  console.log('\x1b[1m  nerviq scan — per-repo comparison\x1b[0m');
-  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
-  console.log(`  Platform: ${summary.platform}  |  Repos: ${summary.repoCount}  |  Average: \x1b[1m${summary.averageScore}/100\x1b[0m`);
-  console.log('');
+  console.log('');
+  console.log('\x1b[1m  nerviq scan — per-repo comparison\x1b[0m');
+  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+  console.log(`  Platform: ${summary.platform}  |  Repos: ${summary.repoCount}  |  Average: \x1b[1m${summary.averageScore}/100\x1b[0m`);
+  if (summary.scoreSemantics?.note) {
+    console.log(`  Score semantics: ${summary.scoreSemantics.note}`);
+  }
+  console.log('');
 
   for (const item of summary.repos) {
     if (item.error) {
@@ -323,9 +467,12 @@ function printScanDetail(summary, options) {
       continue;
     }
     const scoreColor = item.score >= 80 ? '\x1b[32m' : item.score >= 50 ? '\x1b[33m' : '\x1b[31m';
-    console.log(`  \x1b[1m${item.name}\x1b[0m  ${scoreColor}${item.score}/100\x1b[0m  (${item.passed}/${item.total} checks passed)`);
-
-    // Show per-category breakdown if result is available
+    console.log(`  \x1b[1m${item.name}\x1b[0m  ${scoreColor}${item.score}/100\x1b[0m  (${item.passed}/${item.total} checks passed)`);
+    if (item.policyCoverage?.layerKeys?.length > 0) {
+      console.log(`    \x1b[2mPolicy layers: ${item.policyCoverage.layerKeys.join(' -> ')}\x1b[0m`);
+    }
+
+    // Show per-category breakdown if result is available
     if (item.result && item.result.results) {
       const STACK_LANGUAGES = new Set(['python', 'go', 'rust', 'java', 'ruby', 'dotnet', 'php', 'flutter', 'swift', 'kotlin']);
       const categories = {};
@@ -354,28 +501,57 @@ function printScanDetail(summary, options) {
   }
 }
 
-function printOrgSummary(summary, options) {
-  if (options.json) {
-    console.log(JSON.stringify(summary, null, 2));
-    return;
-  }
+function printOrgSummary(summary, options) {
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
 
   console.log('');
-  console.log('\x1b[1m  nerviq org scan\x1b[0m');
-  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
-  console.log(`  Platform: ${summary.platform}`);
-  console.log(`  Repos: ${summary.repoCount}`);
-  console.log(`  Average score: \x1b[1m${summary.averageScore}/100\x1b[0m`);
-  console.log('');
-  console.log('\x1b[1m  Repo              Platform  Score  Top action\x1b[0m');
-  console.log('  ' + '─'.repeat(72));
-  for (const item of summary.repos) {
-    const score = item.score === null ? 'ERR' : String(item.score);
-    const topAction = item.error || item.topAction || '-';
-    console.log(`  ${item.name.padEnd(18)} ${item.platform.padEnd(8)} ${score.padStart(5)}  ${topAction}`);
-  }
-  console.log('');
-}
+  console.log('\x1b[1m  nerviq org scan\x1b[0m');
+  console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+  console.log(`  Platform: ${summary.platform}`);
+  console.log(`  Repos: ${summary.repoCount}`);
+  console.log(`  Average score: \x1b[1m${summary.averageScore}/100\x1b[0m`);
+  if (summary.scoreSemantics?.note) {
+    console.log(`  Score semantics: ${summary.scoreSemantics.note}`);
+  }
+  if (summary.policyCoverage) {
+    console.log(`  Policy coverage: org=${summary.policyCoverage.orgPolicyRepos} team=${summary.policyCoverage.teamPolicyRepos} repo=${summary.policyCoverage.repoPolicyRepos}`);
+  }
+  if (summary.scoreBands) {
+    console.log(`  Bands: strong=${summary.scoreBands.strong} developing=${summary.scoreBands.developing} bootstrap=${summary.scoreBands.bootstrap} unknown=${summary.scoreBands.unknown}`);
+  }
+  console.log('');
+  console.log('\x1b[1m  Repo              Platform  Score  Policy        Top action\x1b[0m');
+  console.log('  ' + '─'.repeat(72));
+  for (const item of summary.repos) {
+    const score = item.score === null ? 'ERR' : String(item.score);
+    const topAction = item.error || item.topAction || '-';
+    const policy = item.policyCoverage?.layerKeys?.length > 0 ? item.policyCoverage.layerKeys.join('/') : '-';
+    console.log(`  ${item.name.padEnd(18)} ${item.platform.padEnd(8)} ${score.padStart(5)}  ${policy.padEnd(12)} ${topAction}`);
+  }
+  if (Array.isArray(summary.topEvidence) && summary.topEvidence.length > 0) {
+    console.log('');
+    console.log('  Common top evidence:');
+    for (const item of summary.topEvidence) {
+      console.log(`    - ${item.key} (${item.repoCount} repos)`);
+    }
+  }
+  console.log('');
+}
+
+function writeStdout(text) {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(text, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
 
 const HELP = `
   nerviq v${version}
@@ -388,20 +564,23 @@ const HELP = `
     nerviq audit --full           Full audit with all checks, weakest areas, badge
     nerviq audit --platform X     Audit specific platform (claude|codex|cursor|copilot|gemini|windsurf|aider|opencode)
     nerviq audit --json           Machine-readable JSON output (for CI)
-    nerviq audit --workspace packages/*     Audit monorepo workspaces with root-vs-package score semantics
-    nerviq scan dir1 dir2         Compare multiple repos side-by-side
-    nerviq org scan dir1 dir2     Aggregate multiple repos into one score table
+    nerviq audit --workspace packages/*     Audit monorepo workspaces with stack-specific package profiles
+    nerviq scan dir1 dir2         Compare multiple repos side-by-side
+    nerviq org scan dir1 dir2     Aggregate multiple repos into one score table
+    nerviq org policy [dir]       Inspect resolved org/team/repo policy layers
     nerviq catalog                Full check catalog (all 8 platforms)
     nerviq catalog --json         Export full check catalog as JSON
     nerviq anti-patterns          Detect anti-patterns in current project
     nerviq anti-patterns --all    Show full anti-pattern catalog
 
-  SETUP
-    nerviq setup                  Generate starter-safe baseline config files
-    nerviq setup --auto           Apply all generated files without prompts
-    nerviq interactive            Step-by-step guided wizard
-    nerviq check-health           Detect regressions + platform format changes between snapshots
-    nerviq doctor                 Self-diagnostics: Node, deps, freshness, platform detection
+  SETUP
+    nerviq setup                  Generate starter-safe baseline config files
+    nerviq setup --auto           Apply all generated files without prompts
+    nerviq interactive            Step-by-step guided wizard
+    nerviq baseline init          Lock the first managed Nerviq baseline for continuous ops
+    nerviq baseline status        Show the current managed baseline contract
+    nerviq check-health           Detect regressions + platform format changes between snapshots
+    nerviq doctor                 Self-diagnostics: Node, deps, freshness, MCP, hook runtime
 
   FIX
     nerviq fix                    Show fixable checks and manual-fix guidance
@@ -414,16 +593,18 @@ const HELP = `
     nerviq rollback --list        Show available rollback points
     nerviq rollback --dry-run     Preview what would be deleted
 
-  IMPROVE
-    nerviq augment                Improvement plan (no writes)
-    nerviq suggest-only           Structured report for sharing (no writes)
-    nerviq plan                   Export proposal bundles with diffs
-    nerviq plan --out plan.json   Save plan to file
-    nerviq apply                  Apply proposals selectively with rollback
-    nerviq apply --dry-run        Preview changes without writing
+  IMPROVE
+    nerviq augment                Improvement plan (no writes)
+    nerviq suggest-only           Structured report for sharing (no writes)
+    nerviq plan                   Export proposal bundles with diffs
+    nerviq plan --campaign X      Export a named upgrade campaign slice
+    nerviq plan --out plan.json   Save plan to file
+    nerviq apply                  Apply proposals selectively with rollback
+    nerviq apply --campaign X     Apply a named upgrade campaign
+    nerviq apply --dry-run        Preview changes without writing
 
   GOVERN
-    nerviq governance             Permission profiles + hooks + policy packs
+    nerviq governance             Permission profiles + hooks + policy packs (the rollout safety layer)
     nerviq governance --json      Machine-readable governance summary
     nerviq benchmark              Baseline vs projected score in isolated temp copy
     nerviq benchmark --external /path  Benchmark an external repo
@@ -441,16 +622,24 @@ const HELP = `
     nerviq migrate --platform X   Platform version migration helper
     nerviq migrate --platform cursor --from v2 --to v3
 
-  MONITOR
+  MONITOR
     nerviq dashboard              Generate static dashboard from latest audit snapshot (or live audit if none)
-    nerviq dashboard --out F      Save dashboard to custom file
-    nerviq dashboard --open       Open dashboard in browser after generating
-    nerviq watch                  Live config monitoring (re-audits on file change)
+    nerviq dashboard --out F      Save dashboard to custom file
+    nerviq dashboard --open       Open dashboard in browser after generating
+    nerviq watch                  Live config monitoring (re-audits on file change)
+    nerviq audit --diff-only --drift-mode ci   PR / CI drift review against the managed baseline
     nerviq history                Audit snapshot history from saved snapshots
-    nerviq compare                Latest vs previous audit snapshot diff
+    nerviq compare                Detailed per-check diff between latest two audit snapshots
     nerviq trend                  Audit snapshot trend over time
-    nerviq trend --out report.md  Export trend report as markdown
-    nerviq feedback               Record recommendation outcomes
+    nerviq trend --out report.md  Export trend report as markdown
+    nerviq audit --snapshot --milestone baseline --tag "baseline"  Save a lifecycle checkpoint
+    nerviq feedback               Record recommendation outcomes
+
+  EXCEPTIONS
+    nerviq exception add --key permissionDeny --owner team --reason "migration in progress" --expires 2026-05-01
+    nerviq exception add --class policy-drift --scope ci --owner team --reason "temporary rollout" --expires 2026-05-01
+    nerviq exception list         Show active and expired exceptions
+    nerviq exception prune        Remove expired exceptions
 
   TEAM PROFILES
     nerviq profile save <name>    Save current preferences as a named profile
@@ -459,8 +648,9 @@ const HELP = `
     nerviq profile export <name>  Export profile JSON for sharing
 
   ADVANCED
-    nerviq deep-review            AI-powered config review (opt-in, uses API key)
-    nerviq serve --port 3000      Start local Nerviq REST API server
+    nerviq deep-review            AI-powered config review (opt-in, uses API key)
+    nerviq deep-review --behavioral  Local behavioral drift review (opt-in, no API)
+    nerviq serve --port 3000      Start local Nerviq REST API server + OpenAPI contract
     nerviq badge                  Generate shields.io badge markdown
     nerviq rules-export           Export recommendation rules as JSON
     nerviq rules-export --out F   Save rules to file
@@ -475,15 +665,24 @@ const HELP = `
     --only A,B        Limit plan/apply to selected proposal IDs
     --profile NAME    Permission profile: read-only | suggest-only | safe-write | power-user
     --team-profile N  Load a saved team profile for audit (overrides threshold/platform)
-    --mcp-pack A,B    Merge MCP packs into setup (e.g. context7-docs,next-devtools)
-    --check-version V Pin catalog to a specific version (warn on mismatch)
-    --format NAME     Output format: json | sarif | otel
-    --webhook URL     Send audit results to a webhook (Slack/Discord/generic JSON)
-    --external PATH   Benchmark an external repo instead of cwd
-    --port N          Port for \`serve\` (default: 3000)
-    --workspace GLOBS Audit workspaces separately and label root governance vs package scores
-    --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
-    --full            Show full audit output (all checks, weakest areas, badge)
+    --mcp-pack A,B    Merge MCP packs into setup (live tool connectors; e.g. context7-docs,next-devtools)
+    --check-version V Pin catalog to a specific version (warn on mismatch)
+    --format NAME     Output format: json | sarif | otel
+    --webhook URL     Send audit results to a webhook (Slack/Discord/generic JSON)
+    --webhook-header H Add a custom webhook header (repeat; format: Name: Value)
+    --webhook-retries N Retry transient webhook failures N times (default: 2)
+    --external PATH   Benchmark an external repo instead of cwd
+    --port N          Port for \`serve\` (default: 3000)
+    --workspace GLOBS Audit workspaces separately with root/package score semantics and stack-specific profiles
+    --diff-only       Audit only changed files / linked config surfaces from git diff
+    --drift-mode M    Continuous posture mode: ci | pr | watch
+    --diff-base SHA   Base SHA for diff-only mode (defaults to PR env vars when present)
+    --diff-head SHA   Head SHA for diff-only mode (defaults to GITHUB_SHA or HEAD)
+    --snapshot        Save snapshot artifact under .claude/nerviq/snapshots/
+    --tag LABEL       Tag the saved snapshot (use with --snapshot; repeat or comma-separate for more)
+    --milestone NAME  Snapshot lifecycle milestone: baseline | post-fix | pre-upgrade | release
+    --campaign A,B    Limit plan/apply to named upgrade campaigns
+    --full            Show full audit output (all checks, weakest areas, badge)
     --lite            Short top-3 scan (default behavior since v1.5.2)
     --dry-run         Preview changes without writing files
     --config-only     Only write config files (.claude/, rules, hooks) — never source code
@@ -493,26 +692,38 @@ const HELP = `
     --auto            Apply all generated files without prompting
     --beginner        Show only the 5 starter commands for first-time users
     --key NAME        Feedback: recommendation key (e.g. permissionDeny)
-    --status VALUE    Feedback: accepted | rejected | deferred
-    --effect VALUE    Feedback: positive | neutral | negative
-    --score-delta N   Feedback: observed score delta
-    --help            Show this help
-    --version         Show version
+    --status VALUE    Feedback: accepted | rejected | deferred
+    --effect VALUE    Feedback: positive | neutral | negative
+    --score-delta N   Feedback: observed score delta
+    --owner NAME      Exception owner
+    --reason TEXT     Exception reason
+    --expires DATE    Exception expiry (ISO date or date-time)
+    --scope NAME      Exception scope: all | ci | watch | pr
+    --class NAME      Exception target class: policy-drift | config-drift | platform-drift | maturity-opportunity
+    --behavioral      Run the opt-in local behavioral drift / outcome-layer review
+    --history         With deep-review --behavioral, show behavioral snapshot history
+    --compare         With deep-review --behavioral, compare the latest two behavioral snapshots
+    --help            Show this help
+    --version         Show version
 
   EXAMPLES
     npx nerviq --beginner
     npx nerviq
     npx nerviq --lite
     npx nerviq --platform cursor
-    npx nerviq audit --workspace packages/*
-    npx nerviq --platform codex augment
-    npx nerviq org scan ./app ./api ./infra
+    npx nerviq audit --workspace packages/*
+    npx nerviq baseline init
+    npx nerviq audit --diff-only --drift-mode ci
+    npx nerviq --platform codex augment
+    npx nerviq org scan ./app ./api ./infra
+    npx nerviq org policy
     npx nerviq scan ./app ./api ./infra
     npx nerviq harmony-audit
     npx nerviq convert --from claude --to codex
     npx nerviq migrate --platform cursor --from v2 --to v3
-    npx nerviq setup --mcp-pack context7-docs
-    npx nerviq apply --plan plan.json --only hooks,commands
+    npx nerviq setup --mcp-pack context7-docs
+    npx nerviq plan --campaign governance-hardening
+    npx nerviq apply --plan plan.json --only hooks,commands
     npx nerviq serve --port 4000
     npx nerviq --json --threshold 70
     npx nerviq catalog --json --out catalog.json
@@ -534,7 +745,7 @@ const BEGINNER_HELP = `
     nerviq setup      Generate a starter-safe baseline
     nerviq fix        Fix what can be fixed or show manual fix guidance
     nerviq augment    Show an improvement plan without writing
-    nerviq doctor     Check install health, freshness, and platform detection
+    nerviq doctor     Check install health, freshness, platform detection, MCP, and hook runtime
 
   SIMPLE PATH
     1. nerviq audit
@@ -579,7 +790,7 @@ async function main() {
     process.exit(0);
   }
 
-  const options = {
+  const options = {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
@@ -598,28 +809,82 @@ async function main() {
     only: parsed.only,
     profile: parsed.profile,
     mcpPacks: parsed.mcpPacks,
-    require: parsed.requireChecks,
-    platform: parsed.platform || 'claude',
-    format: parsed.format || null,
-    port: parsed.port !== null ? Number(parsed.port) : null,
-    workspace: parsed.workspace || null,
-    webhookUrl: parsed.webhookUrl || null,
-    lang: parsed.lang || null,
-    external: parsed.external || null,
-    dir: process.cwd()
-  };
-
-  if (parsed.checkVersion) {
+    require: parsed.requireChecks,
+    platform: parsed.platform || 'claude',
+    platformExplicit: Boolean(parsed.platformExplicit),
+    format: parsed.format || null,
+    port: parsed.port !== null ? Number(parsed.port) : null,
+    workspace: parsed.workspace || null,
+    webhookUrl: parsed.webhookUrl || null,
+    webhookHeaders: Object.fromEntries((parsed.webhookHeaders || []).map((entry) => [entry.name, entry.value])),
+    webhookRetries: parsed.webhookRetries ?? 2,
+    lang: parsed.lang || null,
+    external: parsed.external || null,
+    snapshotTags: parsed.snapshotTags || [],
+    snapshotMilestone: parsed.snapshotMilestone || null,
+    campaigns: parsed.campaigns || [],
+    behavioral: flags.includes('--behavioral'),
+    historyView: flags.includes('--history'),
+    compareView: flags.includes('--compare'),
+    diffOnly: flags.includes('--diff-only'),
+    diffBase: parsed.diffBase || null,
+    diffHead: parsed.diffHead || null,
+    driftMode: parsed.driftMode || null,
+    exceptionOwner: parsed.exceptionOwner || null,
+    exceptionReason: parsed.exceptionReason || null,
+    exceptionExpires: parsed.exceptionExpires || null,
+    exceptionScope: parsed.exceptionScope || null,
+    exceptionClass: parsed.exceptionClass || null,
+    dir: process.cwd()
+  };
+
+  if (options.snapshotTags.length > 0 && !options.snapshot) {
+    console.error('\n  Error: --tag requires --snapshot.\n');
+    process.exit(1);
+  }
+
+  if (options.snapshotMilestone && !options.snapshot) {
+    console.error('\n  Error: --milestone requires --snapshot.\n');
+    process.exit(1);
+  }
+
+  if (options.snapshotMilestone && !SNAPSHOT_MILESTONES.includes(options.snapshotMilestone)) {
+    console.error(`\n  Error: Unsupported milestone '${options.snapshotMilestone}'. Use one of: ${SNAPSHOT_MILESTONES.join(', ')}.\n`);
+    process.exit(1);
+  }
+
+  if (options.diffOnly && options.snapshot) {
+    console.error('\n  Error: --diff-only cannot be combined with --snapshot because diff-only scores are not comparable to full audit snapshots.\n');
+    process.exit(1);
+  }
+
+  if (options.driftMode && !['ci', 'pr', 'watch'].includes(options.driftMode)) {
+    console.error(`\n  Error: Unsupported drift mode '${options.driftMode}'. Use ci, pr, or watch.\n`);
+    process.exit(1);
+  }
+
+  if (parsed.checkVersion) {
     if (parsed.checkVersion !== version) {
       console.error(`\n  Warning: --check-version ${parsed.checkVersion} does not match installed nerviq version ${version}.`);
       console.error(`  Check catalog may differ between versions. To align, run: npm install @nerviq/cli@${parsed.checkVersion}`);
       console.error('');
     }
-    options.checkVersion = parsed.checkVersion;
-  }
-
-  if (parsed.teamProfile) {
-    const { loadProfile, applyProfileToOptions } = require('../src/profiles');
+    options.checkVersion = parsed.checkVersion;
+  }
+
+  const {
+    resolvePolicyLayers,
+    applyPolicyLayersToOptions,
+    formatPolicyContract,
+  } = require('../src/policy-layers');
+  const inheritedPolicyContract = resolvePolicyLayers(options.dir);
+  if (inheritedPolicyContract.layers.some((layer) => layer.valid)) {
+    Object.assign(options, applyPolicyLayersToOptions(inheritedPolicyContract, options));
+    options.policyContract = inheritedPolicyContract;
+  }
+
+  if (parsed.teamProfile) {
+    const { loadProfile, applyProfileToOptions } = require('../src/profiles');
     try {
       const teamProf = loadProfile(options.dir, parsed.teamProfile);
       const merged = applyProfileToOptions(teamProf, options);
@@ -658,10 +923,15 @@ async function main() {
     process.exit(1);
   }
 
-  if (options.format !== null && !['json', 'sarif', 'otel'].includes(options.format)) {
-    console.error(`\n  Error: Unsupported format '${options.format}'. Use 'json', 'sarif', or 'otel'.\n`);
-    process.exit(1);
-  }
+  if (options.format !== null && !['json', 'sarif', 'otel'].includes(options.format)) {
+    console.error(`\n  Error: Unsupported format '${options.format}'. Use 'json', 'sarif', or 'otel'.\n`);
+    process.exit(1);
+  }
+
+  if (options.driftMode && options.format !== null) {
+    console.error('\n  Error: --drift-mode is only supported with normal text output or --json.\n');
+    process.exit(1);
+  }
 
   if (options.port !== null && (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535)) {
     console.error('\n  Error: --port must be an integer between 0 and 65535.\n');
@@ -711,13 +981,13 @@ async function main() {
   }
 
   try {
-    const FULL_COMMAND_SET = new Set([
-      'audit', 'org', 'scan', 'badge', 'augment', 'suggest-only', 'setup', 'plan', 'apply',
-      'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'insights',
-      'history', 'compare', 'trend', 'feedback', 'catalog', 'certify', 'serve', 'help', 'version',
-      // Harmony + Synergy (cross-platform)
-      'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise',
-      'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export',
+    const FULL_COMMAND_SET = new Set([
+      'audit', 'org', 'scan', 'badge', 'augment', 'suggest-only', 'setup', 'plan', 'apply',
+      'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'insights',
+      'history', 'compare', 'trend', 'feedback', 'catalog', 'certify', 'serve', 'baseline', 'exception', 'help', 'version',
+      // Harmony + Synergy (cross-platform)
+      'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise',
+      'harmony-watch', 'harmony-governance', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export',
       'freshness', 'profile', 'migrate',
     ]);
 
@@ -763,33 +1033,51 @@ async function main() {
       }
     }
 
-    if (normalizedCommand === 'scan') {
-      const scanDirs = parsed.extraArgs;
-      if (scanDirs.length === 0) {
-        console.error('\n  Error: scan requires at least one directory argument.');
-        console.error('  Usage: npx nerviq scan dir1 dir2 dir3\n');
-        process.exit(1);
-      }
-      const summary = await scanOrg(scanDirs, options.platform);
-      printScanDetail(summary, options);
-      if (options.threshold !== null && summary.averageScore < options.threshold) {
-        process.exit(1);
-      }
-      process.exit(0);
-    } else if (normalizedCommand === 'org') {
-      const subcommand = parsed.extraArgs[0];
-      const scanDirs = parsed.extraArgs.slice(1);
-      if (subcommand !== 'scan' || scanDirs.length === 0) {
-        console.error('\n  Error: org requires the scan subcommand and at least one directory.');
-        console.error('  Usage: npx nerviq org scan dir1 dir2 dir3\n');
-        process.exit(1);
-      }
-      const summary = await scanOrg(scanDirs, options.platform);
-      printOrgSummary(summary, options);
-      if (options.threshold !== null && summary.averageScore < options.threshold) {
-        process.exit(1);
-      }
-      process.exit(0);
+    if (normalizedCommand === 'scan') {
+      const scanDirs = parsed.extraArgs;
+      if (scanDirs.length === 0) {
+        console.error('\n  Error: scan requires at least one directory argument.');
+        console.error('  Usage: npx nerviq scan dir1 dir2 dir3\n');
+        process.exit(1);
+      }
+      const summary = await scanOrg(scanDirs, options);
+      printScanDetail(summary, options);
+      if (options.threshold !== null && summary.averageScore < options.threshold) {
+        process.exit(1);
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'org') {
+      const subcommand = parsed.extraArgs[0];
+      if (subcommand === 'policy') {
+        const targetDir = parsed.extraArgs[1] ? require('path').resolve(parsed.extraArgs[1]) : options.dir;
+        const contract = resolvePolicyLayers(targetDir);
+        if (options.json) {
+          await writeStdout(JSON.stringify(contract, null, 2) + '\n');
+        } else {
+          console.log('');
+          console.log(formatPolicyContract(contract));
+          console.log('');
+        }
+        process.exit(0);
+      }
+
+      const scanDirs = parsed.extraArgs.slice(1);
+      if (subcommand !== 'scan' || scanDirs.length === 0) {
+        console.error('\n  Error: org requires `scan` or `policy`.');
+        console.error('  Usage: npx nerviq org scan dir1 dir2 dir3');
+        console.error('         npx nerviq org policy [dir]\n');
+        process.exit(1);
+      }
+      const summary = await scanOrg(scanDirs, options);
+      if (options.json) {
+        await writeStdout(JSON.stringify(summary, null, 2) + '\n');
+      } else {
+        printOrgSummary(summary, options);
+      }
+      if (options.threshold !== null && summary.averageScore < options.threshold) {
+        process.exit(1);
+      }
+      process.exit(0);
     } else if (normalizedCommand === 'history') {
       const { formatHistory, readSnapshotIndex } = require('../src/activity');
       // Handle --prune N
@@ -820,7 +1108,7 @@ async function main() {
       console.log('');
       process.exit(0);
     } else if (normalizedCommand === 'compare') {
-      const { compareLatest, formatSnapshotBootstrap } = require('../src/activity');
+      const { compareLatest, formatSnapshotBootstrap, formatSnapshotTags, formatSnapshotMilestone } = require('../src/activity');
       const result = compareLatest(options.dir);
       if (!result) {
         console.log('');
@@ -830,16 +1118,41 @@ async function main() {
       }
       if (options.json) {
         console.log(JSON.stringify(result, null, 2));
-      } else {
-        const sign = result.delta.score >= 0 ? '+' : '';
-        console.log('');
-        console.log(`  Previous snapshot: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})`);
-        console.log(`  Current snapshot:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})`);
+      } else {
+        const sign = result.delta.score >= 0 ? '+' : '';
+        console.log('');
+        console.log(`  Previous snapshot: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})${formatSnapshotMilestone(result.previous.milestone)}${formatSnapshotTags(result.previous.tags)}`);
+        console.log(`  Current snapshot:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})${formatSnapshotMilestone(result.current.milestone)}${formatSnapshotTags(result.current.tags)}`);
         console.log(`  Snapshot delta:    ${sign}${result.delta.score} points`);
         console.log(`  Trend:    ${result.trend}`);
-        if (result.improvements.length > 0) console.log(`  Fixed:    ${result.improvements.join(', ')}`);
-        if (result.regressions.length > 0) console.log(`  New gaps: ${result.regressions.join(', ')}`);
-        console.log('');
+        if (result.detailedDiffAvailable) {
+          console.log('');
+          console.log('  Detailed check diff:');
+          printCompareCheckSection('Regressions', result.regressionDetails, '🔴');
+          printCompareCheckSection('Improvements', result.improvementDetails, '✅');
+          printCompareCheckSection('Newly applicable', result.newlyApplicableDetails, '🆕');
+          printCompareCheckSection('No longer applicable', result.noLongerApplicableDetails, '↩');
+          if (Array.isArray(result.newChecks) && result.newChecks.length > 0) {
+            printCompareCheckSection('New checks', result.newChecks, '➕');
+          }
+          if (Array.isArray(result.removedChecks) && result.removedChecks.length > 0) {
+            printCompareCheckSection('Removed checks', result.removedChecks, '➖');
+          }
+          if (
+            result.regressionDetails.length === 0 &&
+            result.improvementDetails.length === 0 &&
+            result.newlyApplicableDetails.length === 0 &&
+            result.noLongerApplicableDetails.length === 0 &&
+            result.newChecks.length === 0 &&
+            result.removedChecks.length === 0
+          ) {
+            console.log('  No per-check state changes detected.');
+          }
+        } else {
+          if (result.improvements.length > 0) console.log(`  Fixed:    ${result.improvements.join(', ')}`);
+          if (result.regressions.length > 0) console.log(`  New gaps: ${result.regressions.join(', ')}`);
+        }
+        console.log('');
       }
       process.exit(0);
     } else if (normalizedCommand === 'trend') {
@@ -959,9 +1272,11 @@ async function main() {
       process.exit(0);
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {
+        tags: options.snapshotTags,
+        milestone: options.snapshotMilestone,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out && !options.json) {
         const fs = require('fs');
         const md = exportMarkdown(report);
@@ -1092,9 +1407,11 @@ async function main() {
         fs.writeFileSync(options.out, content, 'utf8');
       }
       printGovernanceSummary(summary, options);
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'governance', summary, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'governance', summary, {
+        tags: options.snapshotTags,
+        milestone: options.snapshotMilestone,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out && !options.json) {
         console.log(`  Governance report written to ${options.out}`);
         console.log('');
@@ -1106,9 +1423,11 @@ async function main() {
       }
     } else if (normalizedCommand === 'benchmark') {
       const report = await runBenchmark(options);
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'benchmark', report, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'benchmark', report, {
+        tags: options.snapshotTags,
+        milestone: options.snapshotMilestone,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out) {
         writeBenchmarkReport(report, options.out);
       }
@@ -1125,13 +1444,87 @@ async function main() {
     } else if (normalizedCommand === 'deep-review') {
       const { deepReview } = require('../src/deep-review');
       await deepReview(options);
-    } else if (normalizedCommand === 'interactive') {
-      const { interactive } = require('../src/interactive');
-      await interactive(options);
-    } else if (normalizedCommand === 'watch') {
-      const { watch } = require('../src/watch');
-      await watch(options);
-    } else if (normalizedCommand === 'catalog') {
+    } else if (normalizedCommand === 'interactive') {
+      const { interactive } = require('../src/interactive');
+      await interactive(options);
+    } else if (normalizedCommand === 'baseline') {
+      const {
+        readManagedBaseline,
+        writeManagedBaseline,
+        buildManagedBaselineRecord,
+        formatManagedBaselineStatus,
+      } = require('../src/continuous-ops');
+      const subcommand = parsed.extraArgs[0] || 'status';
+
+      if (subcommand === 'status') {
+        const baseline = readManagedBaseline(options.dir);
+        if (options.json) {
+          console.log(JSON.stringify(baseline, null, 2));
+        } else {
+          console.log('');
+          console.log(formatManagedBaselineStatus(options.dir, baseline));
+          console.log('');
+        }
+        process.exit(0);
+      }
+
+      if (subcommand === 'init') {
+        const existingBaseline = readManagedBaseline(options.dir);
+        if (existingBaseline && !flags.includes('--force')) {
+          console.error('\n  Error: Managed baseline already exists. Use `nerviq baseline status` to inspect it, or rerun with --force to replace it.\n');
+          process.exit(1);
+        }
+
+        const auditResult = await audit({ ...options, silent: true });
+        const analysisReport = await analyzeProject({ ...options, mode: 'augment' });
+        const detectedPlatforms = detectPlatforms(options.dir);
+        const snapshot = writeSnapshotArtifact(options.dir, 'audit', auditResult, {
+          tags: [...options.snapshotTags, 'baseline'],
+          milestone: 'baseline',
+          sourceCommand: 'baseline init',
+          managedBaseline: true,
+        });
+        const baselineRecord = buildManagedBaselineRecord({
+          dir: options.dir,
+          platform: options.platform,
+          auditResult,
+          analysisReport,
+          snapshotArtifact: snapshot,
+          currentPlatforms: detectedPlatforms,
+        });
+        const saved = writeManagedBaseline(options.dir, baselineRecord);
+
+        if (options.json) {
+          console.log(JSON.stringify({
+            ...baselineRecord,
+            baselinePath: saved.relativePath,
+          }, null, 2));
+        } else {
+          console.log('');
+          console.log('  nerviq baseline init');
+          console.log('  ═══════════════════════════════════════');
+          console.log(`  Managed baseline written: ${saved.relativePath}`);
+          console.log(`  Snapshot: ${snapshot.relativePath}`);
+          console.log(`  Score: ${baselineRecord.baselineAudit.score}/100`);
+          console.log(`  Operating profile: ${baselineRecord.operatingProfile.label || 'n/a'}`);
+          console.log(`  Adoption plan: ${baselineRecord.adoptionPlan || 'n/a'}`);
+          console.log(`  Active platforms: ${(baselineRecord.detectedPlatforms || []).join(', ') || 'none detected'}`);
+          console.log('');
+          console.log('  Next:');
+          console.log('    - nerviq audit --diff-only --drift-mode ci');
+          console.log('    - nerviq watch');
+          console.log('    - nerviq plan --campaign governance-hardening');
+          console.log('');
+        }
+        process.exit(0);
+      }
+
+      console.error('\n  Error: baseline supports `init` and `status`.\n');
+      process.exit(1);
+    } else if (normalizedCommand === 'watch') {
+      const { watch } = require('../src/watch');
+      await watch(options);
+    } else if (normalizedCommand === 'catalog') {
       const { generateCatalogWithVersion, writeCatalogJson } = require('../src/catalog');
       if (options.out) {
         const result = writeCatalogJson(options.out);
@@ -1202,9 +1595,10 @@ async function main() {
       const address = server.address();
       const resolvedPort = address && typeof address === 'object' ? address.port : options.port;
       console.log('');
-      console.log(`  nerviq API listening on http://127.0.0.1:${resolvedPort}`);
-      console.log('  Endpoints: /api/health, /api/catalog, /api/audit, /api/harmony');
-      console.log('');
+      console.log(`  nerviq API listening on http://127.0.0.1:${resolvedPort}`);
+      console.log('  Endpoints: /api/openapi.json, /api/health, /api/catalog, /api/audit, /api/harmony');
+      console.log(`  Contract: http://127.0.0.1:${resolvedPort}/api/openapi.json`);
+      console.log('');
 
       const closeServer = () => {
         server.close(() => process.exit(0));
@@ -1429,18 +1823,74 @@ async function main() {
         }
       }
       process.exit(0);
-    } else if (normalizedCommand === 'suggest-rules') {
-      const { analyzeSuggestions, formatSuggestions } = require('../src/auto-suggest');
-      const suggestions = analyzeSuggestions(options.dir);
-      if (options.json) {
-        console.log(JSON.stringify(suggestions, null, 2));
-      } else {
-        console.log('');
-        console.log(formatSuggestions(suggestions));
-        console.log('');
-      }
-      process.exit(0);
-    } else if (normalizedCommand === 'profile') {
+    } else if (normalizedCommand === 'suggest-rules') {
+      const { analyzeSuggestions, formatSuggestions } = require('../src/auto-suggest');
+      const suggestions = analyzeSuggestions(options.dir);
+      if (options.json) {
+        console.log(JSON.stringify(suggestions, null, 2));
+      } else {
+        console.log('');
+        console.log(formatSuggestions(suggestions));
+        console.log('');
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'exception') {
+      const {
+        listExceptions,
+        addException,
+        pruneExpiredExceptions,
+        formatExceptionsList,
+      } = require('../src/continuous-ops');
+      const subcommand = parsed.extraArgs[0] || 'list';
+
+      if (subcommand === 'list') {
+        const records = listExceptions(options.dir);
+        if (options.json) {
+          console.log(JSON.stringify(records, null, 2));
+        } else {
+          console.log('');
+          console.log(formatExceptionsList(records));
+          console.log('');
+        }
+        process.exit(0);
+      }
+
+      if (subcommand === 'add') {
+        const result = addException(options.dir, {
+          key: parsed.feedbackKey || null,
+          watchClass: options.exceptionClass,
+          owner: options.exceptionOwner,
+          reason: options.exceptionReason,
+          expiresAt: options.exceptionExpires,
+          scope: options.exceptionScope || 'all',
+        });
+        if (options.json) {
+          console.log(JSON.stringify(result.record, null, 2));
+        } else {
+          console.log('');
+          console.log(`  Exception added: ${result.record.id}`);
+          console.log(`  Target: ${result.record.key || result.record.watchClass}`);
+          console.log(`  Owner: ${result.record.owner}`);
+          console.log(`  Scope: ${result.record.scope}`);
+          console.log(`  Expires: ${result.record.expiresAt}`);
+          console.log('');
+        }
+        process.exit(0);
+      }
+
+      if (subcommand === 'prune') {
+        const result = pruneExpiredExceptions(options.dir);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`\n  Pruned ${result.removedCount} expired exception(s). Kept ${result.keptCount} active record(s).\n`);
+        }
+        process.exit(0);
+      }
+
+      console.error('\n  Error: exception supports `add`, `list`, and `prune`.\n');
+      process.exit(1);
+    } else if (normalizedCommand === 'profile') {
       const { saveProfile, loadProfile, listProfiles, exportProfile, formatProfileList, formatProfile } = require('../src/profiles');
       const subcommand = parsed.extraArgs[0];
       const profileArg = parsed.extraArgs[1];
@@ -1982,30 +2432,117 @@ async function main() {
       process.exit(0);
     } else if (normalizedCommand === 'setup') {
       await setup(options);
-      if (options.snapshot) {
-        const postSetupResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
-        const snapshot = writeSnapshotArtifact(options.dir, 'audit', postSetupResult, {
-          sourceCommand: 'setup',
-        });
-        if (!options.json) {
-          console.log(`  Snapshot saved: ${snapshot.relativePath}`);
-        }
-      }
-    } else {
-      if (options.workspace) {
-        const summary = await auditWorkspaces(options.dir, options.workspace, options.platform);
-        printWorkspaceSummary(summary, options);
-        if (options.threshold !== null && summary.averageScore < options.threshold) {
-          process.exit(1);
-        }
-        process.exit(0);
+      if (options.snapshot) {
+        const postSetupResult = await audit({ dir: options.dir, silent: true, platform: options.platform });
+        const snapshot = writeSnapshotArtifact(options.dir, 'audit', postSetupResult, {
+          tags: options.snapshotTags,
+          milestone: options.snapshotMilestone,
+          sourceCommand: 'setup',
+        });
+        if (!options.json) {
+          console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        }
       }
-      const result = await audit(options);
-      if (options.out) {
-        const fs = require('fs');
-        const path = require('path');
-        const outPath = path.resolve(options.out);
-        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    } else {
+      if (options.workspace) {
+        const summary = await auditWorkspaces(options.dir, options.workspace, options.platform);
+        printWorkspaceSummary(summary, options);
+        if (options.threshold !== null && summary.averageScore < options.threshold) {
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+      let result;
+      const renderAuditJsonLocally = options.json && Boolean(options.driftMode);
+      if (options.diffOnly) {
+        const { getChangedFiles, buildDiffOnlyAuditView, printDiffOnlyAudit } = require('../src/diff-only');
+        const fullResult = await audit({ ...options, silent: true });
+        const diffInfo = getChangedFiles(options.dir, {
+          diffBase: options.diffBase,
+          diffHead: options.diffHead,
+        });
+        result = buildDiffOnlyAuditView(fullResult, diffInfo);
+      } else {
+        result = renderAuditJsonLocally
+          ? await audit({ ...options, silent: true })
+          : await audit(options);
+      }
+
+      if (options.driftMode) {
+        const { buildContinuousStatus, formatContinuousStatus } = require('../src/continuous-ops');
+        let campaigns = [];
+        try {
+          const planBundle = await buildProposalBundle({
+            dir: options.dir,
+            platform: options.platform,
+            profile: options.profile,
+            mcpPacks: options.mcpPacks,
+            campaigns: [],
+          });
+          campaigns = planBundle.campaigns || [];
+        } catch {
+          campaigns = [];
+        }
+
+        result = {
+          ...result,
+          continuousStatus: buildContinuousStatus({
+            dir: options.dir,
+            auditResult: result,
+            mode: options.driftMode,
+            currentPlatforms: detectPlatforms(options.dir),
+            campaigns,
+          }),
+        };
+      }
+
+      if (options.policyContract && options.policyContract.layers.some((layer) => layer.valid)) {
+        result = {
+          ...result,
+          policyLayers: options.policyContract,
+        };
+      }
+
+      if (options.diffOnly) {
+        const { printDiffOnlyAudit } = require('../src/diff-only');
+        if (options.json) {
+          console.log(JSON.stringify({
+            version,
+            timestamp: new Date().toISOString(),
+            ...result,
+          }, null, 2));
+        } else {
+          console.log(printDiffOnlyAudit(result));
+          if (result.continuousStatus) {
+            const { formatContinuousStatus } = require('../src/continuous-ops');
+            console.log(formatContinuousStatus(result.continuousStatus));
+            console.log('');
+          }
+        }
+      } else if (renderAuditJsonLocally) {
+        console.log(JSON.stringify({
+          version,
+          timestamp: new Date().toISOString(),
+          ...result,
+        }, null, 2));
+      } else {
+        if (!options.json && options.policyContract && options.policyContract.layers.some((layer) => layer.valid)) {
+          console.log('');
+          console.log(formatPolicyContract(options.policyContract));
+          console.log('');
+        }
+        if (!options.json && result.continuousStatus) {
+          const { formatContinuousStatus } = require('../src/continuous-ops');
+          console.log('');
+          console.log(formatContinuousStatus(result.continuousStatus));
+          console.log('');
+        }
+      }
+      if (options.out) {
+        const fs = require('fs');
+        const path = require('path');
+        const outPath = path.resolve(options.out);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
         fs.writeFileSync(outPath, JSON.stringify(result, null, 2), 'utf8');
         if (!options.json) {
           console.log(`\n  Audit report written to ${options.out}\n`);
@@ -2013,32 +2550,39 @@ async function main() {
       }
       if (options.webhookUrl) {
         try {
-          const { sendWebhook, formatSlackMessage } = require('../src/integrations');
+          const { sendWebhook, formatSlackMessage, formatGenericAuditWebhookEvent } = require('../src/integrations');
           // Auto-detect Slack vs generic by URL pattern
           const isSlack = options.webhookUrl.includes('hooks.slack.com');
           const isDiscord = options.webhookUrl.includes('discord.com/api/webhooks');
           let payload;
-          if (isSlack) {
-            payload = formatSlackMessage(result);
-          } else if (isDiscord) {
-            const { formatDiscordMessage } = require('../src/integrations');
-            payload = formatDiscordMessage(result);
-          } else {
-            // Generic webhook: send full JSON audit result
-            payload = { platform: result.platform, score: result.score, passed: result.passed, failed: result.failed, results: result.results };
-          }
-          const webhookResp = await sendWebhook(options.webhookUrl, payload);
-          if (!options.json) {
-            if (webhookResp.ok) {
-              console.log(`  Webhook sent: ${options.webhookUrl} (${webhookResp.status})`);
-            } else {
-              console.error(`  Webhook failed: ${webhookResp.status} — ${webhookResp.body.slice(0, 200)}`);
-            }
-          }
-        } catch (webhookErr) {
-          if (!options.json) console.error(`  Webhook error: ${webhookErr.message}`);
-        }
-      }
+          if (isSlack) {
+            payload = formatSlackMessage(result);
+          } else if (isDiscord) {
+            const { formatDiscordMessage } = require('../src/integrations');
+            payload = formatDiscordMessage(result);
+          } else {
+            payload = formatGenericAuditWebhookEvent(result);
+          }
+          const webhookResp = await sendWebhook(options.webhookUrl, payload, {
+            headers: options.webhookHeaders,
+            retries: options.webhookRetries,
+          });
+          if (!options.json) {
+            if (webhookResp.ok) {
+              const retryNote = webhookResp.attempts > 1 ? ` after ${webhookResp.attempts} attempts` : '';
+              console.log(`  Webhook sent${retryNote}: ${options.webhookUrl} (${webhookResp.status})`);
+            } else {
+              const retryNote = webhookResp.attempts > 1 ? ` after ${webhookResp.attempts} attempts` : '';
+              console.error(`  Webhook failed${retryNote}: ${webhookResp.status} — ${webhookResp.body.slice(0, 200)}`);
+            }
+          }
+        } catch (webhookErr) {
+          if (!options.json) {
+            const retryNote = webhookErr.attempts > 1 ? ` after ${webhookErr.attempts} attempts` : '';
+            console.error(`  Webhook error${retryNote}: ${webhookErr.message}`);
+          }
+        }
+      }
       if (options.feedback && !options.json && options.format === null) {
         const feedbackTargets = options.lite
           ? (result.liteSummary?.topNextActions || [])
@@ -2058,26 +2602,37 @@ async function main() {
           console.log('');
         }
       }
-      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
-        sourceCommand: normalizedCommand,
-      }) : null;
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
+        tags: options.snapshotTags,
+        milestone: options.snapshotMilestone,
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (snapshot && !options.json) {
         console.log(`  Snapshot saved: ${snapshot.relativePath}`);
         console.log(`  Snapshot index: ${snapshot.indexPath}`);
         console.log('');
       }
-      if (options.threshold !== null && result.score < options.threshold) {
-        if (!options.json) {
-          console.error(`\n  Error: Threshold not met — score ${result.score}/100 is below required ${options.threshold}/100.`);
-          console.error('  Why: Your project audit score is lower than the minimum threshold set via --threshold.');
-          console.error('  Fix: Run `npx nerviq augment` to see improvement suggestions, then re-audit.');
+      if (options.threshold !== null && result.score < options.threshold) {
+        if (!options.json) {
+          console.error(`\n  Error: Threshold not met — score ${result.score}/100 is below required ${options.threshold}/100.`);
+          console.error('  Why: Your project audit score is lower than the minimum threshold set via --threshold.');
+          console.error('  Fix: Run `npx nerviq augment` to see improvement suggestions, then re-audit.');
           console.error('  Docs: https://github.com/nerviq/nerviq#ci-integration\n');
-        }
-        process.exit(1);
-      }
-      if (options.require && options.require.length > 0) {
-        const failedRequired = options.require.filter(key => {
-          const check = result.results.find(r => r.key === key);
+        }
+        process.exit(1);
+      }
+      if (result.continuousStatus && result.continuousStatus.gate === 'fail') {
+        if (!options.json) {
+          console.error('\n  Error: Continuous drift gate failed.');
+          console.error(`  Why: ${result.continuousStatus.gateLabel}.`);
+          console.error('  Fix: review the blocking drift items or add a temporary exception with owner/reason/expiry.');
+          console.error('  Docs: https://github.com/nerviq/nerviq#readme\n');
+        }
+        process.exit(1);
+      }
+      if (options.require && options.require.length > 0) {
+        const failedRequired = options.require.filter(key => {
+          const check = result.results.find(r => r.key === key);
           return !check || check.passed !== true;
         });
         if (failedRequired.length > 0) {