aios-core 4.2.5 → 4.2.7

package/.aios-core/development/scripts/workflow-state-manager.js

@@ -17,13 +17,15 @@
  * - Each session picks up where the last left off via state file
  *
  * @module workflow-state-manager
- * @version 1.0.0
+ * @version 2.0.0
  */
 
 const fs = require('fs').promises;
 const path = require('path');
 const yaml = require('js-yaml');
 
+const WORKFLOW_STATE_VERSION = '2.0';
+
 class WorkflowStateManager {
   /**
    * @param {Object} [options={}]
@@ -64,6 +66,7 @@ class WorkflowStateManager {
     const instanceId = this._generateInstanceId(wf.id);
 
     const state = {
+      state_version: WORKFLOW_STATE_VERSION,
       workflow_id: wf.id,
       workflow_name: wf.name || wf.id,
       instance_id: instanceId,
@@ -137,6 +140,130 @@ class WorkflowStateManager {
     return state;
   }
 
+  // ============ Runtime-First Next Action ============
+
+  /**
+   * Build normalized execution state from runtime signals.
+   * Deterministic priority:
+   * blocked > qa_rejected > ci_red > completed > in_development > ready_for_validation > unknown
+   *
+   * @param {Object} [signals={}]
+   * @param {string} [signals.story_status]
+   * @param {string} [signals.qa_status]
+   * @param {string} [signals.ci_status]
+   * @param {boolean} [signals.has_uncommitted_changes]
+   * @returns {{ state: string, reasons: string[], normalized: Object }}
+   */
+  evaluateExecutionState(signals = {}) {
+    const storyStatus = String(signals.story_status || 'unknown').toLowerCase();
+    const qaStatus = String(signals.qa_status || 'unknown').toLowerCase();
+    const ciStatus = String(signals.ci_status || 'unknown').toLowerCase();
+    const hasUncommitted = Boolean(signals.has_uncommitted_changes);
+
+    const reasons = [];
+    let state = 'unknown';
+
+    if (storyStatus === 'blocked') {
+      state = 'blocked';
+      reasons.push('story status is blocked');
+    } else if (qaStatus === 'rejected' || qaStatus === 'fail' || qaStatus === 'failed') {
+      state = 'qa_rejected';
+      reasons.push(`qa status is ${qaStatus}`);
+    } else if (ciStatus === 'red' || ciStatus === 'failed' || ciStatus === 'error') {
+      state = 'ci_red';
+      reasons.push(`ci status is ${ciStatus}`);
+    } else if (storyStatus === 'done' || storyStatus === 'completed') {
+      state = 'completed';
+      reasons.push(`story status is ${storyStatus}`);
+    } else if (storyStatus === 'in_progress' || storyStatus === 'review') {
+      if (hasUncommitted) {
+        state = 'in_development';
+        reasons.push('story in progress with uncommitted changes');
+      } else {
+        state = 'ready_for_validation';
+        reasons.push('story in progress with clean working tree');
+      }
+    }
+
+    return {
+      state,
+      reasons,
+      normalized: {
+        story_status: storyStatus,
+        qa_status: qaStatus,
+        ci_status: ciStatus,
+        has_uncommitted_changes: hasUncommitted,
+      },
+    };
+  }
+
+  /**
+   * Deterministic next-action recommendation for runtime-first flows.
+   *
+   * @param {Object} [signals={}]
+   * @param {Object} [options={}]
+   * @param {string} [options.story]
+   * @returns {{ state: string, command: string, agent: string, rationale: string, confidence: number }}
+   */
+  getNextActionRecommendation(signals = {}, options = {}) {
+    const result = this.evaluateExecutionState(signals);
+    const storyArg = options.story ? ` ${options.story}` : '';
+
+    const map = {
+      blocked: {
+        command: `*orchestrate-status${storyArg}`,
+        agent: '@po',
+        rationale: 'Story is blocked. Surface blockers and unblock path first.',
+        confidence: 0.95,
+      },
+      qa_rejected: {
+        command: `*apply-qa-fixes${storyArg}`,
+        agent: '@dev',
+        rationale: 'QA rejected the story. Apply fixes before progressing.',
+        confidence: 0.95,
+      },
+      ci_red: {
+        command: '*run-tests',
+        agent: '@dev',
+        rationale: 'CI is red. Reproduce and fix failing tests/checks first.',
+        confidence: 0.92,
+      },
+      completed: {
+        command: `*close-story${storyArg}`,
+        agent: '@po',
+        rationale: 'Story is complete. Close lifecycle and move to next item.',
+        confidence: 0.9,
+      },
+      in_development: {
+        command: '*run-tests',
+        agent: '@dev',
+        rationale: 'Code is in progress with local changes. Validate before QA handoff.',
+        confidence: 0.85,
+      },
+      ready_for_validation: {
+        command: `*review-build${storyArg}`,
+        agent: '@qa',
+        rationale: 'Development appears stable. Proceed to QA structured review.',
+        confidence: 0.82,
+      },
+      unknown: {
+        command: `*next${storyArg}`,
+        agent: '@dev',
+        rationale: 'Context is incomplete. Request explicit workflow guidance.',
+        confidence: 0.4,
+      },
+    };
+
+    const recommendation = map[result.state] || map.unknown;
+    return {
+      state: result.state,
+      command: recommendation.command,
+      agent: recommendation.agent,
+      rationale: recommendation.rationale,
+      confidence: recommendation.confidence,
+    };
+  }
+
   /**
    * Load state from file
    * @param {string} instanceId

package/.aios-core/development/tasks/next.md

@@ -4,6 +4,9 @@
 
 Suggest next commands based on current workflow context using the Workflow Intelligence System (WIS). Helps users navigate workflows efficiently without memorizing command sequences.
 
+AIOS 4.0.4 runtime-first mode adds deterministic next-step recommendation from
+execution signals (story/qa/ci/diff) via `workflow-state-manager`.
+
 ## Task Definition (AIOS Task Format V1.0)
 
 ```yaml
@@ -88,7 +91,23 @@ const context = await engine.buildContext({
 });
 ```
 
-### Step 3: Get Suggestions
+### Step 3: Runtime-First Deterministic Recommendation (Preferred)
+```javascript
+const { WorkflowStateManager } = require('.aios-core/development/scripts/workflow-state-manager');
+const manager = new WorkflowStateManager();
+
+const runtimeNext = manager.getNextActionRecommendation(
+  {
+    story_status: context.projectState?.storyStatus || 'unknown',
+    qa_status: context.projectState?.qaStatus || 'unknown',
+    ci_status: context.projectState?.ciStatus || 'unknown',
+    has_uncommitted_changes: context.projectState?.hasUncommittedChanges || false,
+  },
+  { story: args.story || context.storyPath || '' },
+);
+```
+
+### Step 4: Get WIS Suggestions (Fallback / enrichment)
 ```javascript
 const result = await engine.suggestNext(context);
 
@@ -103,15 +122,27 @@ const result = await engine.suggestNext(context);
 // }
 ```
 
-### Step 4: Format Output
+### Step 5: Format Output
 ```javascript
 const formatter = require('.aios-core/workflow-intelligence/engine/output-formatter');
 
-// Limit to top 3 unless --all flag
-const displaySuggestions = args.all ? result.suggestions : result.suggestions.slice(0, 3);
+const runtimeSuggestion = {
+  command: runtimeNext.command,
+  args: '',
+  description: runtimeNext.rationale,
+  confidence: runtimeNext.confidence,
+  priority: 1,
+};
+const mergedSuggestions = [runtimeSuggestion, ...(result.suggestions || [])];
+const displaySuggestions = args.all ? mergedSuggestions : mergedSuggestions.slice(0, 3);
 
 // Display formatted output
-formatter.displaySuggestions(result.workflow, result.currentState, result.confidence, displaySuggestions);
+formatter.displaySuggestions({
+  workflow: result.workflow || 'runtime_first',
+  currentState: runtimeNext.state,
+  confidence: runtimeNext.confidence,
+  suggestions: displaySuggestions,
+});
 ```
 
 ---

package/.aios-core/hooks/ids-post-commit.js

@@ -15,6 +15,25 @@ const path = require('path');
 
 const REPO_ROOT = path.resolve(__dirname, '../..');
 
+function isDocsOnlyPath(relativePath) {
+  const p = String(relativePath || '').replace(/\\/g, '/');
+  if (!p) return false;
+
+  if (p.startsWith('docs/')) return true;
+  if (p === 'README.md') return true;
+  if (p === 'CHANGELOG.md') return true;
+  if (p === 'CONTRIBUTING.md') return true;
+  if (p === 'CODE_OF_CONDUCT.md') return true;
+  if (p === 'AGENTS.md') return true;
+
+  return false;
+}
+
+function isDocsOnlyCommit(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) return false;
+  return changes.every((c) => isDocsOnlyPath(c.relativePath));
+}
+
 function getChangedFilesFromLastCommit() {
   try {
     const output = execSync('git diff-tree --no-commit-id --name-status -r HEAD', {
@@ -52,7 +71,11 @@ function getChangedFilesFromLastCommit() {
       }
 
       if (!filePath) continue;
-      changes.push({ action, filePath: path.resolve(REPO_ROOT, filePath) });
+      changes.push({
+        action,
+        relativePath: filePath,
+        filePath: path.resolve(REPO_ROOT, filePath),
+      });
     }
 
     return changes;
@@ -67,6 +90,11 @@ async function main() {
 
   if (changes.length === 0) return;
 
+  if (process.env.AIOS_IDS_FORCE !== '1' && isDocsOnlyCommit(changes)) {
+    console.log('[IDS-Hook] Docs-only commit detected, skipping registry update.');
+    return;
+  }
+
   try {
     const { RegistryUpdater } = require(path.resolve(REPO_ROOT, '.aios-core/core/ids/registry-updater.js'));
     const updater = new RegistryUpdater();

package/.aios-core/hooks/ids-pre-push.js

@@ -16,6 +16,25 @@ const path = require('path');
 
 const REPO_ROOT = path.resolve(__dirname, '../..');
 
+function isDocsOnlyPath(relativePath) {
+  const p = String(relativePath || '').replace(/\\/g, '/');
+  if (!p) return false;
+
+  if (p.startsWith('docs/')) return true;
+  if (p === 'README.md') return true;
+  if (p === 'CHANGELOG.md') return true;
+  if (p === 'CONTRIBUTING.md') return true;
+  if (p === 'CODE_OF_CONDUCT.md') return true;
+  if (p === 'AGENTS.md') return true;
+
+  return false;
+}
+
+function isDocsOnlyPush(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) return false;
+  return changes.every((c) => isDocsOnlyPath(c.relativePath));
+}
+
 function getChangedFilesSinceRemote() {
   try {
     const trackingBranch = execSync('git rev-parse --abbrev-ref --symbolic-full-name @{u}', {
@@ -58,7 +77,11 @@ function getChangedFilesSinceRemote() {
       }
 
       if (!filePath) continue;
-      changes.push({ action, filePath: path.resolve(REPO_ROOT, filePath) });
+      changes.push({
+        action,
+        relativePath: filePath,
+        filePath: path.resolve(REPO_ROOT, filePath),
+      });
     }
 
     return changes;
@@ -76,6 +99,11 @@ async function main() {
     process.exit(0);
   }
 
+  if (process.env.AIOS_IDS_FORCE !== '1' && isDocsOnlyPush(changes)) {
+    console.log('[IDS-Hook] Docs-only push detected, skipping registry update.');
+    process.exit(0);
+  }
+
   try {
     const { RegistryUpdater } = require(path.resolve(REPO_ROOT, '.aios-core/core/ids/registry-updater.js'));
     const updater = new RegistryUpdater();

package/.aios-core/infrastructure/contracts/compatibility/aios-4.0.4.yaml

@@ -0,0 +1,44 @@
+release: "AIOS 4.0.4"
+updated_at: "2026-02-16"
+source_of_truth:
+  docs_matrix: "docs/ide-integration.md"
+  validator: ".aios-core/infrastructure/scripts/validate-parity.js"
+
+global_required_checks:
+  - paths
+
+ide_matrix:
+  - ide: "claude-code"
+    display_name: "Claude Code"
+    expected_status: "Works"
+    required_checks:
+      - claude-sync
+      - claude-integration
+  - ide: "gemini"
+    display_name: "Gemini CLI"
+    expected_status: "Works"
+    required_checks:
+      - gemini-sync
+      - gemini-integration
+  - ide: "codex"
+    display_name: "Codex CLI"
+    expected_status: "Limited"
+    required_checks:
+      - codex-sync
+      - codex-integration
+      - codex-skills
+  - ide: "cursor"
+    display_name: "Cursor"
+    expected_status: "Limited"
+    required_checks:
+      - cursor-sync
+  - ide: "github-copilot"
+    display_name: "GitHub Copilot"
+    expected_status: "Limited"
+    required_checks:
+      - github-copilot-sync
+  - ide: "antigravity"
+    display_name: "AntiGravity"
+    expected_status: "Limited"
+    required_checks:
+      - antigravity-sync

package/.aios-core/infrastructure/scripts/validate-parity.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
+const yaml = require('js-yaml');
 const { spawnSync } = require('child_process');
 const { validateClaudeIntegration } = require('./validate-claude-integration');
 const { validateCodexIntegration } = require('./validate-codex-integration');
@@ -10,10 +12,16 @@ const { validateCodexSkills } = require('./codex-skills-sync/validate');
 const { validatePaths } = require('./validate-paths');
 
 function parseArgs(argv = process.argv.slice(2)) {
-  const args = new Set(argv);
+  const args = new Set(
+    argv.filter((arg) => !arg.startsWith('--contract=') && !arg.startsWith('--diff=')),
+  );
+  const contractArg = argv.find((arg) => arg.startsWith('--contract='));
+  const diffArg = argv.find((arg) => arg.startsWith('--diff='));
   return {
     quiet: args.has('--quiet') || args.has('-q'),
     json: args.has('--json'),
+    contractPath: contractArg ? contractArg.slice('--contract='.length) : null,
+    diffPath: diffArg ? diffArg.slice('--diff='.length) : null,
   };
 }
 
@@ -31,6 +39,25 @@ function runSyncValidate(ide, projectRoot) {
   };
 }
 
+function getDefaultContractPath(projectRoot = process.cwd()) {
+  return path.join(
+    projectRoot,
+    '.aios-core',
+    'infrastructure',
+    'contracts',
+    'compatibility',
+    'aios-4.0.4.yaml',
+  );
+}
+
+function loadCompatibilityContract(contractPath) {
+  if (!contractPath || !fs.existsSync(contractPath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(contractPath, 'utf8');
+  return yaml.load(raw);
+}
+
 function normalizeResult(input) {
   if (!input || typeof input !== 'object') {
     return { ok: false, errors: ['Validator returned invalid result'], warnings: [] };
@@ -43,6 +70,152 @@ function normalizeResult(input) {
   };
 }
 
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function validateCompatibilityContract(contract, resultById, options = {}) {
+  const violations = [];
+
+  if (!contract || typeof contract !== 'object') {
+    return ['Compatibility contract is missing or invalid'];
+  }
+
+  const matrix = Array.isArray(contract.ide_matrix) ? contract.ide_matrix : [];
+  if (matrix.length === 0) {
+    return ['Compatibility contract ide_matrix is empty'];
+  }
+
+  const docsPath = options.docsPath;
+  if (!docsPath || !fs.existsSync(docsPath)) {
+    violations.push(`Compatibility matrix document not found: ${docsPath || 'undefined'}`);
+    return violations;
+  }
+  const docsContent = fs.readFileSync(docsPath, 'utf8');
+
+  for (const ide of matrix) {
+    const ideName = ide.ide || 'unknown';
+    const displayName = ide.display_name || ideName;
+    const requiredChecks = Array.isArray(ide.required_checks) ? ide.required_checks : [];
+    const expectedStatus = ide.expected_status;
+
+    if (!expectedStatus) {
+      violations.push(`Contract missing expected_status for IDE "${ideName}"`);
+    }
+
+    const rowRegex = new RegExp(
+      `\\|\\s*${escapeRegex(displayName)}\\s*\\|\\s*${escapeRegex(expectedStatus || '')}\\s*\\|`,
+      'i',
+    );
+    if (!rowRegex.test(docsContent)) {
+      violations.push(
+        `Docs matrix mismatch for "${displayName}": expected status "${expectedStatus}" in ${options.docsPathRelative}`,
+      );
+    }
+
+    for (const checkId of requiredChecks) {
+      const checkResult = resultById[checkId];
+      if (!checkResult) {
+        violations.push(`Contract requires unknown check "${checkId}" for IDE "${ideName}"`);
+        continue;
+      }
+      if (!checkResult.ok) {
+        violations.push(`Contract violation for "${ideName}": required check "${checkId}" failed`);
+      }
+    }
+  }
+
+  const globalRequiredChecks = Array.isArray(contract.global_required_checks)
+    ? contract.global_required_checks
+    : [];
+  for (const checkId of globalRequiredChecks) {
+    const checkResult = resultById[checkId];
+    if (!checkResult) {
+      violations.push(`Contract requires unknown global check "${checkId}"`);
+      continue;
+    }
+    if (!checkResult.ok) {
+      violations.push(`Contract violation: global required check "${checkId}" failed`);
+    }
+  }
+
+  return violations;
+}
+
+function sortUnique(values = []) {
+  return [...new Set(values)].sort();
+}
+
+function diffCompatibilityContracts(currentContract, previousContract) {
+  if (!currentContract || !previousContract) {
+    return null;
+  }
+
+  const currentRelease = currentContract.release || null;
+  const previousRelease = previousContract.release || null;
+  const releaseChanged = currentRelease !== previousRelease;
+
+  const currentGlobalChecks = sortUnique(currentContract.global_required_checks || []);
+  const previousGlobalChecks = sortUnique(previousContract.global_required_checks || []);
+  const globalChecksAdded = currentGlobalChecks.filter((item) => !previousGlobalChecks.includes(item));
+  const globalChecksRemoved = previousGlobalChecks.filter((item) => !currentGlobalChecks.includes(item));
+
+  const currentByIde = Object.fromEntries((currentContract.ide_matrix || []).map((item) => [item.ide, item]));
+  const previousByIde = Object.fromEntries((previousContract.ide_matrix || []).map((item) => [item.ide, item]));
+  const ideKeys = sortUnique([...Object.keys(currentByIde), ...Object.keys(previousByIde)]);
+
+  const ideChanges = [];
+  for (const ide of ideKeys) {
+    const current = currentByIde[ide];
+    const previous = previousByIde[ide];
+
+    if (!previous && current) {
+      ideChanges.push({ ide, type: 'added', current });
+      continue;
+    }
+    if (previous && !current) {
+      ideChanges.push({ ide, type: 'removed', previous });
+      continue;
+    }
+
+    const currentStatus = current.expected_status || null;
+    const previousStatus = previous.expected_status || null;
+    const statusChanged = currentStatus !== previousStatus;
+    const currentChecks = sortUnique(current.required_checks || []);
+    const previousChecks = sortUnique(previous.required_checks || []);
+    const checksAdded = currentChecks.filter((item) => !previousChecks.includes(item));
+    const checksRemoved = previousChecks.filter((item) => !currentChecks.includes(item));
+
+    if (statusChanged || checksAdded.length > 0 || checksRemoved.length > 0) {
+      ideChanges.push({
+        ide,
+        type: 'changed',
+        status: { previous: previousStatus, current: currentStatus },
+        required_checks: {
+          added: checksAdded,
+          removed: checksRemoved,
+        },
+      });
+    }
+  }
+
+  return {
+    from_release: previousRelease,
+    to_release: currentRelease,
+    release_changed: releaseChanged,
+    global_required_checks: {
+      added: globalChecksAdded,
+      removed: globalChecksRemoved,
+    },
+    ide_changes: ideChanges,
+    has_changes:
+      releaseChanged
+      || globalChecksAdded.length > 0
+      || globalChecksRemoved.length > 0
+      || ideChanges.length > 0,
+  };
+}
+
 function runParityValidation(options = {}, deps = {}) {
   const projectRoot = options.projectRoot || process.cwd();
   const runSync = deps.runSyncValidate || runSyncValidate;
@@ -51,6 +224,15 @@ function runParityValidation(options = {}, deps = {}) {
   const runGeminiIntegration = deps.validateGeminiIntegration || validateGeminiIntegration;
   const runCodexSkills = deps.validateCodexSkills || validateCodexSkills;
   const runPaths = deps.validatePaths || validatePaths;
+  const resolvedContractPath = options.contractPath
+    ? path.resolve(projectRoot, options.contractPath)
+    : getDefaultContractPath(projectRoot);
+  const loadContract = deps.loadCompatibilityContract || loadCompatibilityContract;
+  const contract = loadContract(resolvedContractPath);
+  const resolvedDiffPath = options.diffPath ? path.resolve(projectRoot, options.diffPath) : null;
+  const previousContract = resolvedDiffPath ? loadContract(resolvedDiffPath) : null;
+  const docsPath = path.join(projectRoot, 'docs', 'ide-integration.md');
+  const docsPathRelative = path.relative(projectRoot, docsPath);
   const checks = [
     { id: 'claude-sync', exec: () => runSync('claude-code', projectRoot) },
     { id: 'claude-integration', exec: () => runClaudeIntegration({ projectRoot }) },
@@ -58,6 +240,9 @@ function runParityValidation(options = {}, deps = {}) {
     { id: 'codex-integration', exec: () => runCodexIntegration({ projectRoot }) },
     { id: 'gemini-sync', exec: () => runSync('gemini', projectRoot) },
     { id: 'gemini-integration', exec: () => runGeminiIntegration({ projectRoot }) },
+    { id: 'cursor-sync', exec: () => runSync('cursor', projectRoot) },
+    { id: 'github-copilot-sync', exec: () => runSync('github-copilot', projectRoot) },
+    { id: 'antigravity-sync', exec: () => runSync('antigravity', projectRoot) },
     { id: 'codex-skills', exec: () => runCodexSkills({ projectRoot, strict: true, quiet: true }) },
     { id: 'paths', exec: () => runPaths({ projectRoot }) },
   ];
@@ -66,15 +251,60 @@ function runParityValidation(options = {}, deps = {}) {
     const normalized = normalizeResult(check.exec());
     return { id: check.id, ...normalized };
   });
+  const resultById = Object.fromEntries(results.map((r) => [r.id, r]));
+  const contractViolations = validateCompatibilityContract(contract, resultById, {
+    docsPath,
+    docsPathRelative,
+  });
+  const contractSummary = contract
+    ? {
+        release: contract.release || null,
+        path: path.relative(projectRoot, resolvedContractPath),
+      }
+    : {
+        release: null,
+        path: path.relative(projectRoot, resolvedContractPath),
+      };
 
   return {
-    ok: results.every((r) => r.ok),
+    ok: results.every((r) => r.ok) && contractViolations.length === 0,
     checks: results,
+    contract: contractSummary,
+    contractDiff: diffCompatibilityContracts(contract, previousContract),
+    contractViolations,
   };
 }
 
 function formatHumanReport(result) {
   const lines = [];
+  if (result.contract && result.contract.release) {
+    lines.push(`Compatibility Contract: ${result.contract.release} (${result.contract.path})`);
+    lines.push('');
+  }
+  if (result.contractDiff) {
+    lines.push(
+      `Contract Diff: ${result.contractDiff.from_release || 'unknown'} -> ${result.contractDiff.to_release || 'unknown'}`,
+    );
+    if (!result.contractDiff.has_changes) {
+      lines.push('- no changes');
+    } else {
+      if (result.contractDiff.release_changed) {
+        lines.push('- release changed');
+      }
+      const globalAdded = result.contractDiff.global_required_checks.added || [];
+      const globalRemoved = result.contractDiff.global_required_checks.removed || [];
+      if (globalAdded.length > 0) {
+        lines.push(`- global checks added: ${globalAdded.join(', ')}`);
+      }
+      if (globalRemoved.length > 0) {
+        lines.push(`- global checks removed: ${globalRemoved.join(', ')}`);
+      }
+      for (const ideChange of result.contractDiff.ide_changes || []) {
+        lines.push(`- ${ideChange.ide}: ${ideChange.type}`);
+      }
+    }
+    lines.push('');
+  }
   for (const check of result.checks) {
     lines.push(`${check.ok ? '✅' : '❌'} ${check.id}`);
     if (check.errors.length > 0) {
@@ -84,6 +314,11 @@ function formatHumanReport(result) {
       lines.push(...check.warnings.map((w) => `⚠️ ${w}`));
     }
   }
+  if (Array.isArray(result.contractViolations) && result.contractViolations.length > 0) {
+    lines.push('');
+    lines.push('❌ Compatibility Contract Violations');
+    lines.push(...result.contractViolations.map((v) => `- ${v}`));
+  }
   lines.push('');
   lines.push(result.ok ? '✅ Parity validation passed' : '❌ Parity validation failed');
   return lines.join('\n');
@@ -116,4 +351,5 @@ module.exports = {
   runParityValidation,
   normalizeResult,
   formatHumanReport,
+  diffCompatibilityContracts,
 };