@nerviq/cli 0.0.1 → 0.9.0-beta.2

package/src/harmony/governance.js

@@ -0,0 +1,313 @@
+/**
+ * H8. Harmony Governance - Cross-Platform Policy Enforcement
+ *
+ * Evaluates cross-platform governance posture: minimum trust levels,
+ * required instruction coverage, MCP alignment, and per-platform compliance.
+ *
+ * Zero external dependencies - imports from sibling/parent modules only.
+ */
+
+// ─── Required canonical sections every platform should cover ──────────────────
+
+const REQUIRED_INSTRUCTION_SECTIONS = [
+  { key: 'role', label: 'Role / Identity', description: 'Define who the AI assistant is in this project.' },
+  { key: 'commands', label: 'Verification Commands', description: 'Test, lint, and build commands the AI should use.' },
+  { key: 'language', label: 'Language Preference', description: 'Communication language for the AI.' },
+  { key: 'permissions', label: 'Permission Boundaries', description: 'What the AI is allowed and denied to do.' },
+  { key: 'context', label: 'Project Context', description: 'Architecture, stack, and codebase overview.' },
+  { key: 'safety', label: 'Safety / Secret Protection', description: 'Rules for handling secrets and sensitive files.' },
+];
+
+// ─── Trust posture definitions ────────────────────────────────────────────────
+
+const TRUST_LEVELS = {
+  strict: {
+    level: 1,
+    label: 'Strict',
+    description: 'Read-only or suggest-only. No file writes without approval.',
+    minPermissions: ['deny-write', 'deny-destructive'],
+  },
+  guarded: {
+    level: 2,
+    label: 'Guarded',
+    description: 'Safe writes with explicit deny rules and hook enforcement.',
+    minPermissions: ['deny-destructive', 'secret-protection'],
+  },
+  standard: {
+    level: 3,
+    label: 'Standard',
+    description: 'Accept-edits with common-sense deny rules.',
+    minPermissions: ['secret-protection'],
+  },
+  permissive: {
+    level: 4,
+    label: 'Permissive',
+    description: 'Broad autonomy with minimal restrictions.',
+    minPermissions: [],
+  },
+  unrestricted: {
+    level: 5,
+    label: 'Unrestricted',
+    description: 'Full bypass, only for internal research.',
+    minPermissions: [],
+  },
+};
+
+// ─── Platform trust detection ─────────────────────────────────────────────────
+
+/**
+ * Infer trust level from a platform's audit/governance data.
+ */
+function inferTrustLevel(platformGovernance) {
+  if (!platformGovernance) return TRUST_LEVELS.unrestricted;
+
+  const { hasPermissions, hasDenyRules, hasSecretProtection, defaultMode } = platformGovernance;
+
+  if (defaultMode === 'plan' || defaultMode === 'read-only') return TRUST_LEVELS.strict;
+  if (hasDenyRules && hasSecretProtection) return TRUST_LEVELS.guarded;
+  if (hasPermissions || hasSecretProtection) return TRUST_LEVELS.standard;
+  if (hasPermissions) return TRUST_LEVELS.permissive;
+  return TRUST_LEVELS.unrestricted;
+}
+
+// ─── Governance evaluation ────────────────────────────────────────────────────
+
+/**
+ * Evaluate instruction coverage for a single platform.
+ */
+function evaluateInstructionCoverage(platformSections) {
+  const covered = [];
+  const missing = [];
+
+  for (const required of REQUIRED_INSTRUCTION_SECTIONS) {
+    const found = (platformSections || []).some(s => {
+      const key = s.key || s;
+      return key === required.key || key.includes(required.key);
+    });
+    if (found) {
+      covered.push(required);
+    } else {
+      missing.push(required);
+    }
+  }
+
+  return {
+    total: REQUIRED_INSTRUCTION_SECTIONS.length,
+    covered: covered.length,
+    missing: missing.length,
+    coveredSections: covered,
+    missingSections: missing,
+    percentage: Math.round((covered.length / REQUIRED_INSTRUCTION_SECTIONS.length) * 100),
+  };
+}
+
+/**
+ * Evaluate MCP server alignment across platforms.
+ */
+function evaluateMcpAlignment(platformAudits) {
+  const mcpByPlatform = {};
+  const allServers = new Set();
+
+  for (const audit of (platformAudits || [])) {
+    const servers = audit.mcpServers || [];
+    mcpByPlatform[audit.platform] = new Set(servers);
+    for (const s of servers) allServers.add(s);
+  }
+
+  const alignment = [];
+  for (const server of allServers) {
+    const presentIn = [];
+    const missingFrom = [];
+
+    for (const audit of (platformAudits || [])) {
+      if (mcpByPlatform[audit.platform] && mcpByPlatform[audit.platform].has(server)) {
+        presentIn.push(audit.platform);
+      } else {
+        missingFrom.push(audit.platform);
+      }
+    }
+
+    alignment.push({
+      server,
+      presentIn,
+      missingFrom,
+      aligned: missingFrom.length === 0,
+    });
+  }
+
+  return {
+    totalServers: allServers.size,
+    fullyAligned: alignment.filter(a => a.aligned).length,
+    misaligned: alignment.filter(a => !a.aligned).length,
+    servers: alignment,
+  };
+}
+
+/**
+ * Get the complete harmony governance summary.
+ *
+ * @param {Object|null} canonicalModel - The canonical model from canon.js
+ * @param {Array} [platformAudits] - Array of per-platform audit results with governance data
+ * @returns {Object} Full governance summary
+ */
+function getHarmonyGovernanceSummary(canonicalModel, platformAudits) {
+  const audits = platformAudits || [];
+
+  // 1. Minimum trust posture (lowest acceptable across all platforms)
+  const trustLevels = audits.map(audit => ({
+    platform: audit.platform,
+    trust: inferTrustLevel(audit.governance),
+  }));
+
+  const lowestTrust = trustLevels.length > 0
+    ? trustLevels.reduce((min, curr) =>
+        curr.trust.level < min.trust.level ? curr : min
+      )
+    : null;
+
+  const minimumTrustPosture = {
+    level: lowestTrust ? lowestTrust.trust : TRUST_LEVELS.unrestricted,
+    lowestPlatform: lowestTrust ? lowestTrust.platform : null,
+    perPlatform: trustLevels.map(t => ({
+      platform: t.platform,
+      level: t.trust.label,
+      levelNumber: t.trust.level,
+      description: t.trust.description,
+    })),
+  };
+
+  // 2. Required instruction coverage per platform
+  const instructionCoverage = {
+    required: REQUIRED_INSTRUCTION_SECTIONS,
+    perPlatform: audits.map(audit => ({
+      platform: audit.platform,
+      ...evaluateInstructionCoverage(audit.sections),
+    })),
+  };
+
+  // 3. MCP alignment
+  const mcpAlignment = evaluateMcpAlignment(audits);
+
+  // 4. Compliance: per-platform governance status
+  const platformCompliance = audits.map(audit => {
+    const coverage = evaluateInstructionCoverage(audit.sections);
+    const trust = inferTrustLevel(audit.governance);
+    const gaps = [];
+
+    if (coverage.missing > 0) {
+      gaps.push(`Missing ${coverage.missing} required instruction section(s): ${coverage.missingSections.map(s => s.key).join(', ')}`);
+    }
+
+    if (trust.level >= 4) {
+      gaps.push(`Trust level "${trust.label}" is too permissive for production use`);
+    }
+
+    if (audit.governance && !audit.governance.hasSecretProtection) {
+      gaps.push('No secret protection configured');
+    }
+
+    if (audit.governance && !audit.governance.hasDenyRules) {
+      gaps.push('No deny rules configured');
+    }
+
+    return {
+      platform: audit.platform,
+      compliant: gaps.length === 0,
+      score: audit.score || 0,
+      trustLevel: trust.label,
+      coveragePercent: coverage.percentage,
+      gaps,
+    };
+  });
+
+  return {
+    minimumTrustPosture,
+    instructionCoverage,
+    mcpAlignment,
+    platformCompliance,
+    evaluatedAt: new Date().toISOString(),
+  };
+}
+
+// ─── Report formatting ────────────────────────────────────────────────────────
+
+const COLORS = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', blue: '\x1b[36m',
+};
+const col = (text, color) => `${COLORS[color] || ''}${text}${COLORS.reset}`;
+
+/**
+ * Format the governance summary as a human-readable console report.
+ */
+function formatHarmonyGovernanceReport(summary, options) {
+  if (options && options.json) {
+    return JSON.stringify(summary, null, 2);
+  }
+
+  const lines = [];
+
+  lines.push('');
+  lines.push(col('  Harmony Governance Report', 'bold'));
+  lines.push(col('  ═══════════════════════════════════════', 'dim'));
+  lines.push('');
+
+  // Trust posture
+  lines.push(col('  Trust Posture', 'bold'));
+  for (const entry of summary.minimumTrustPosture.perPlatform) {
+    const trustColor = entry.levelNumber <= 2 ? 'green' : entry.levelNumber <= 3 ? 'yellow' : 'red';
+    lines.push(`    ${entry.platform}: ${col(entry.level, trustColor)} — ${entry.description}`);
+  }
+  if (summary.minimumTrustPosture.lowestPlatform) {
+    lines.push(`    ${col('Minimum:', 'dim')} ${summary.minimumTrustPosture.level.label} (${summary.minimumTrustPosture.lowestPlatform})`);
+  }
+  lines.push('');
+
+  // Instruction coverage
+  lines.push(col('  Instruction Coverage', 'bold'));
+  for (const entry of summary.instructionCoverage.perPlatform) {
+    const pctColor = entry.percentage >= 80 ? 'green' : entry.percentage >= 50 ? 'yellow' : 'red';
+    lines.push(`    ${entry.platform}: ${col(`${entry.percentage}%`, pctColor)} (${entry.covered}/${entry.total})`);
+    if (entry.missingSections.length > 0) {
+      lines.push(`      ${col('Missing:', 'dim')} ${entry.missingSections.map(s => s.key).join(', ')}`);
+    }
+  }
+  lines.push('');
+
+  // MCP alignment
+  lines.push(col('  MCP Alignment', 'bold'));
+  lines.push(`    Total servers: ${summary.mcpAlignment.totalServers}`);
+  lines.push(`    Fully aligned: ${col(String(summary.mcpAlignment.fullyAligned), 'green')}`);
+  lines.push(`    Misaligned: ${col(String(summary.mcpAlignment.misaligned), summary.mcpAlignment.misaligned > 0 ? 'yellow' : 'green')}`);
+  for (const server of summary.mcpAlignment.servers) {
+    if (!server.aligned) {
+      lines.push(`      ${col(server.server, 'yellow')}: missing from ${server.missingFrom.join(', ')}`);
+    }
+  }
+  lines.push('');
+
+  // Platform compliance
+  lines.push(col('  Platform Compliance', 'bold'));
+  for (const entry of summary.platformCompliance) {
+    const status = entry.compliant
+      ? col('COMPLIANT', 'green')
+      : col('NON-COMPLIANT', 'red');
+    lines.push(`    ${entry.platform}: ${status} (score: ${entry.score}, trust: ${entry.trustLevel}, coverage: ${entry.coveragePercent}%)`);
+    for (const gap of entry.gaps) {
+      lines.push(`      ${col('GAP:', 'yellow')} ${gap}`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  getHarmonyGovernanceSummary,
+  formatHarmonyGovernanceReport,
+  inferTrustLevel,
+  evaluateInstructionCoverage,
+  evaluateMcpAlignment,
+  TRUST_LEVELS,
+  REQUIRED_INSTRUCTION_SECTIONS,
+};

package/src/harmony/memory.js

@@ -0,0 +1,238 @@
+/**
+ * H7. Shared Memory / Knowledge Layer
+ *
+ * Cross-platform knowledge storage in .claudex/harmony/ directory.
+ * Persists canonical models, drift history, platform scores,
+ * recommendation outcomes, and routing history.
+ *
+ * Zero external dependencies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HARMONY_DIR = '.claudex/harmony';
+
+const STATE_FILES = {
+  canon: 'canon.json',
+  driftHistory: 'drift-history.json',
+  platformScores: 'platform-scores.json',
+  recommendationOutcomes: 'recommendation-outcomes.json',
+  routingHistory: 'routing-history.json',
+};
+
+// ─── File I/O helpers ─────────────────────────────────────────────────────────
+
+function ensureHarmonyDir(dir) {
+  const harmonyPath = path.join(dir, HARMONY_DIR);
+  fs.mkdirSync(harmonyPath, { recursive: true });
+  return harmonyPath;
+}
+
+function readJsonSafe(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return null;
+  }
+}
+
+function writeJsonAtomic(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+// ─── State management ─────────────────────────────────────────────────────────
+
+/**
+ * Save the full harmony state to disk.
+ *
+ * @param {string} dir - Project root directory
+ * @param {Object} state - State object with optional keys: canon, driftHistory, platformScores, recommendationOutcomes, routingHistory
+ */
+function saveHarmonyState(dir, state) {
+  const harmonyPath = ensureHarmonyDir(dir);
+
+  for (const [key, filename] of Object.entries(STATE_FILES)) {
+    if (state[key] !== undefined) {
+      const filePath = path.join(harmonyPath, filename);
+      writeJsonAtomic(filePath, state[key]);
+    }
+  }
+
+  // Write a combined manifest
+  const manifest = {
+    lastUpdated: new Date().toISOString(),
+    files: Object.entries(STATE_FILES)
+      .filter(([key]) => state[key] !== undefined)
+      .map(([key, filename]) => ({ key, filename })),
+  };
+  writeJsonAtomic(path.join(harmonyPath, 'manifest.json'), manifest);
+}
+
+/**
+ * Load the full harmony state from disk.
+ *
+ * @param {string} dir - Project root directory
+ * @returns {Object} State object with all available keys populated
+ */
+function loadHarmonyState(dir) {
+  const harmonyPath = path.join(dir, HARMONY_DIR);
+  const state = {};
+
+  for (const [key, filename] of Object.entries(STATE_FILES)) {
+    const filePath = path.join(harmonyPath, filename);
+    const data = readJsonSafe(filePath);
+    if (data !== null) {
+      state[key] = data;
+    }
+  }
+
+  // Load manifest for metadata
+  const manifest = readJsonSafe(path.join(harmonyPath, 'manifest.json'));
+  if (manifest) {
+    state._manifest = manifest;
+  }
+
+  return state;
+}
+
+// ─── History helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Get the full harmony history with optional filtering.
+ *
+ * @param {string} dir - Project root
+ * @param {Object} [filter] - Optional filter: { platform, since, type }
+ * @returns {Object} { driftHistory, platformScores, routingHistory, recommendationOutcomes }
+ */
+function getHarmonyHistory(dir, filter) {
+  const state = loadHarmonyState(dir);
+
+  const result = {
+    driftHistory: state.driftHistory || [],
+    platformScores: state.platformScores || [],
+    routingHistory: state.routingHistory || [],
+    recommendationOutcomes: state.recommendationOutcomes || [],
+  };
+
+  if (!filter) return result;
+
+  const { platform, since, type } = filter;
+
+  const matchesFilter = (entry) => {
+    if (platform && entry.platform !== platform) return false;
+    if (since && entry.timestamp && entry.timestamp < since) return false;
+    if (type && entry.type !== type) return false;
+    return true;
+  };
+
+  if (platform || since || type) {
+    result.driftHistory = result.driftHistory.filter(matchesFilter);
+    result.platformScores = result.platformScores.filter(matchesFilter);
+    result.routingHistory = result.routingHistory.filter(matchesFilter);
+    result.recommendationOutcomes = result.recommendationOutcomes.filter(matchesFilter);
+  }
+
+  return result;
+}
+
+// ─── Append helpers (for incremental state updates) ───────────────────────────
+
+function appendToArray(dir, stateKey, entry) {
+  const state = loadHarmonyState(dir);
+  const arr = Array.isArray(state[stateKey]) ? state[stateKey] : [];
+  arr.push({
+    ...entry,
+    timestamp: entry.timestamp || new Date().toISOString(),
+  });
+  saveHarmonyState(dir, { ...state, [stateKey]: arr });
+}
+
+/**
+ * Record a routing outcome (which platform was used for what, and how it went).
+ *
+ * @param {string} dir - Project root
+ * @param {Object} outcome
+ * @param {string} outcome.taskType - e.g. 'bug-fix', 'ci-review'
+ * @param {string} outcome.platform - e.g. 'claude', 'codex'
+ * @param {string} outcome.result - 'success' | 'partial' | 'failure'
+ * @param {string} [outcome.notes] - Free-form notes
+ */
+function recordRoutingOutcome(dir, outcome) {
+  appendToArray(dir, 'routingHistory', {
+    type: 'routing',
+    taskType: outcome.taskType,
+    platform: outcome.platform,
+    result: outcome.result,
+    notes: outcome.notes || '',
+  });
+}
+
+/**
+ * Record a drift measurement.
+ *
+ * @param {string} dir - Project root
+ * @param {Object} drift
+ * @param {string} drift.platform - Platform that drifted
+ * @param {number} drift.driftScore - Measured drift value
+ * @param {Array} [drift.driftedFields] - Which fields drifted
+ */
+function recordDrift(dir, drift) {
+  appendToArray(dir, 'driftHistory', {
+    type: 'drift',
+    platform: drift.platform,
+    driftScore: drift.driftScore,
+    driftedFields: drift.driftedFields || [],
+  });
+}
+
+/**
+ * Record a platform audit score snapshot.
+ *
+ * @param {string} dir - Project root
+ * @param {string} platform - Platform key
+ * @param {number} score - Audit score
+ * @param {Object} [details] - Additional audit details
+ */
+function recordPlatformScore(dir, platform, score, details) {
+  appendToArray(dir, 'platformScores', {
+    type: 'score',
+    platform,
+    score,
+    details: details || {},
+  });
+}
+
+/**
+ * Record a recommendation outcome.
+ *
+ * @param {string} dir - Project root
+ * @param {Object} outcome
+ * @param {string} outcome.recommendation - The recommendation text
+ * @param {string} outcome.platform - Target platform
+ * @param {string} outcome.result - 'accepted' | 'rejected' | 'deferred'
+ * @param {string} [outcome.reason] - Why the outcome was chosen
+ */
+function recordRecommendationOutcome(dir, outcome) {
+  appendToArray(dir, 'recommendationOutcomes', {
+    type: 'recommendation',
+    recommendation: outcome.recommendation,
+    platform: outcome.platform,
+    result: outcome.result,
+    reason: outcome.reason || '',
+  });
+}
+
+module.exports = {
+  saveHarmonyState,
+  loadHarmonyState,
+  getHarmonyHistory,
+  recordRoutingOutcome,
+  recordDrift,
+  recordPlatformScore,
+  recordRecommendationOutcome,
+  HARMONY_DIR,
+  STATE_FILES,
+};