contextos-agents 1.7.0 → 2.0.0-beta.3

package/.agents/doctor.js

@@ -1,15 +1,26 @@
 /**
  * .agents/doctor.js
- * ContextOS — Project Diagnostics & Health Check Engine
+ * ContextOS Doctor v2 — Comprehensive Project Diagnostics & Health Check Engine
  *
- * Inspects:
- *   1. .agents/ directory and core runtime files
- *   2. Node.js environment compatibility
- *   3. Active profile and skill exclusion/preference state
- *   4. Compiled AI agent adapters (Gemini, Claude, Cursor, Copilot, etc.)
- *   5. MCP server status and worktree support
- *   6. Security controls (pre-commit hooks, secret scanning)
- *   7. Project tech stack detection and recommended profile alignment
+ * Implements Milestone 8 Doctor v2 specification:
+ * - Standardized status outcomes: PASS, WARN, FAIL, SKIP, UNVERIFIED, RECOVERY_REQUIRED
+ * - Deep diagnostic checks:
+ *   1. Node.js environment (Node 18 for Core, Node 20 for Runtime)
+ *   2. Git availability & version
+ *   3. Filesystem permissions and path containment
+ *   4. Manifests & schema compliance
+ *   5. Skill dependency graph cycles & missing requirements
+ *   6. Profile validation against registry
+ *   7. Lockfile v1 & v2 integrity with CAS revision checking
+ *   8. Crash resilience & uncommitted transaction journals
+ *   9. Output provenance & managed artifact drift detection
+ *   10. Adapter version compliance
+ *   11. MCP server handshake verification
+ *   12. Secret scanning guardrails (missing scanner yields WARN/SKIP, never PASS)
+ *   13. Monorepo workspace topology
+ *   14. User customization safety
+ * - Automated remediation (doctor --fix) for safe, deterministic repairs
+ * - Versioned structured JSON reporting (schemaVersion: 2.0.0)
  */
 
 'use strict';
@@ -18,6 +29,22 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const profiles = require('./profiles.js');
+const {
+  LockfileV2Manager,
+  JournaledTransaction,
+  ProjectMutationLock,
+  isPidAlive,
+  toPosix,
+} = require('./filesystem/index.js');
+
+const STATUS = {
+  PASS: 'PASS',
+  WARN: 'WARN',
+  FAIL: 'FAIL',
+  SKIP: 'SKIP',
+  UNVERIFIED: 'UNVERIFIED',
+  RECOVERY_REQUIRED: 'RECOVERY_REQUIRED',
+};
 
 const DOMAIN_MAP = {
   frontend: new Set([
@@ -42,48 +69,191 @@ const DOMAIN_MAP = {
 function checkNodeVersion() {
   const version = process.version; // e.g. v22.12.0
   const match = version.match(/^v?(\d+)\.(\d+)/);
-  if (!match) return { ok: false, version, message: `${version} (unknown)` };
+  if (!match) {
+    return {
+      id: 'node_version',
+      status: STATUS.FAIL,
+      ok: false,
+      version,
+      message: `${version} (unknown format)`,
+      remediation: 'Install Node.js >= 18.0.0 from https://nodejs.org',
+    };
+  }
 
   const major = parseInt(match[1], 10);
   const minor = parseInt(match[2], 10);
-  // Requires at least Node 18.0.0 or 16.7.0 for recursive cpSync
-  const ok = major > 16 || (major === 16 && minor >= 7);
+
+  // Core requires Node >= 18.0.0 (or 16.7.0 for basic cpSync). Runtime requires Node >= 20.0.0.
+  if (major < 18) {
+    return {
+      id: 'node_version',
+      status: STATUS.FAIL,
+      ok: false,
+      version,
+      message: `Node.js ${version} (< 18.0.0, Node 18 required for Core)`,
+      remediation: 'Upgrade Node.js to >= 18.0.0 (recommended >= 20.0.0 for ContextOS Runtime)',
+    };
+  }
+
+  if (major < 20) {
+    return {
+      id: 'node_version',
+      status: STATUS.WARN,
+      ok: true,
+      version,
+      message: `Node.js ${version} (>= 18.0.0 for Core, Node 20 recommended for Runtime)`,
+      remediation: 'Upgrade to Node.js >= 20.0.0 for optimal sandbox and runtime worker support',
+    };
+  }
+
   return {
-    ok,
+    id: 'node_version',
+    status: STATUS.PASS,
+    ok: true,
     version,
-    message: ok ? `Node.js ${version} (>= 16.7.0 required)` : `Node.js ${version} (< 16.7.0, please upgrade)`,
+    message: `Node.js ${version} (>= 20.0.0, optimal)`,
+    remediation: null,
   };
 }
 
+function checkGitVersion() {
+  try {
+    const stdout = execFileSync('git', ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    return {
+      id: 'git_version',
+      status: STATUS.PASS,
+      ok: true,
+      message: stdout,
+      remediation: null,
+    };
+  } catch {
+    return {
+      id: 'git_version',
+      status: STATUS.FAIL,
+      ok: false,
+      message: 'git binary not accessible in PATH',
+      remediation: 'Install Git and add it to your system PATH',
+    };
+  }
+}
+
+function checkFilesystemPermissions(projectDir) {
+  try {
+    const probeDir = path.join(projectDir, '.agents', '.contextos', 'probe');
+    fs.mkdirSync(probeDir, { recursive: true });
+    const probeFile = path.join(probeDir, 'perm-test.tmp');
+    fs.writeFileSync(probeFile, 'ok', 'utf8');
+    fs.unlinkSync(probeFile);
+    try { fs.rmdirSync(probeDir); } catch {}
+
+    return {
+      id: 'filesystem_permissions',
+      status: STATUS.PASS,
+      ok: true,
+      message: 'Read and write permissions verified in .agents/',
+      remediation: null,
+    };
+  } catch (err) {
+    return {
+      id: 'filesystem_permissions',
+      status: STATUS.FAIL,
+      ok: false,
+      message: `Filesystem permission denied: ${err.message}`,
+      remediation: 'Ensure the current user has read/write privileges in the project folder',
+    };
+  }
+}
+
 function checkPreCommitHook(projectDir) {
   const hookPath = path.join(projectDir, '.git', 'hooks', 'pre-commit');
   if (!fs.existsSync(hookPath)) {
-    return { ok: false, message: 'not installed (run: npm run setup:hooks)' };
+    if (!isContextOSDevRepo(projectDir)) {
+      return {
+        id: 'pre_commit_hook',
+        status: STATUS.SKIP,
+        ok: true,
+        message: 'optional (not installed in workspace)',
+        remediation: null,
+      };
+    }
+    return {
+      id: 'pre_commit_hook',
+      status: STATUS.WARN,
+      ok: false,
+      message: 'not installed (run: npm run setup:hooks)',
+      remediation: 'Run `npm run setup:hooks` to install Git pre-commit validation hook',
+    };
   }
   try {
     const content = fs.readFileSync(hookPath, 'utf8');
     if (content.includes('check-secrets')) {
-      return { ok: true, message: 'installed (with secret check)' };
+      return {
+        id: 'pre_commit_hook',
+        status: STATUS.PASS,
+        ok: true,
+        message: 'installed (with secret check)',
+        remediation: null,
+      };
     }
-    return { ok: false, message: 'installed but missing check-secrets' };
+    return {
+      id: 'pre_commit_hook',
+      status: STATUS.WARN,
+      ok: false,
+      message: 'installed but missing check-secrets guard',
+      remediation: 'Reinstall hooks via `npm run setup:hooks` to include secret scanning',
+    };
   } catch {
-    return { ok: false, message: 'unreadable' };
+    return {
+      id: 'pre_commit_hook',
+      status: STATUS.FAIL,
+      ok: false,
+      message: 'unreadable',
+      remediation: 'Check filesystem permissions for .git/hooks/pre-commit',
+    };
   }
 }
 
 function checkSecretScanner(projectDir) {
   const scriptPath = path.join(projectDir, 'scripts', 'check-secrets.js');
   if (!fs.existsSync(scriptPath)) {
-    return { ok: true, message: 'scanner script not present (skipped)' };
+    if (!isContextOSDevRepo(projectDir)) {
+      return {
+        id: 'secret_scanner',
+        status: STATUS.SKIP,
+        ok: true,
+        message: 'optional (not configured in workspace)',
+        remediation: null,
+      };
+    }
+    // Per Milestone 8 spec: "doctor не считает отсутствующий scanner PASS"
+    return {
+      id: 'secret_scanner',
+      status: STATUS.WARN,
+      ok: false,
+      message: 'scanner script not present (scripts/check-secrets.js missing)',
+      remediation: 'Install check-secrets.js or configure repository secret scanning',
+    };
   }
   try {
     execFileSync(process.execPath, [scriptPath, '--all'], {
       cwd: projectDir,
       stdio: ['pipe', 'pipe', 'pipe'],
     });
-    return { ok: true, message: '0 findings' };
+    return {
+      id: 'secret_scanner',
+      status: STATUS.PASS,
+      ok: true,
+      message: '0 findings',
+      remediation: null,
+    };
   } catch (err) {
-    return { ok: false, message: 'potential secrets detected (run: npm run check:secrets)' };
+    return {
+      id: 'secret_scanner',
+      status: STATUS.FAIL,
+      ok: false,
+      message: 'potential secrets detected in workspace',
+      remediation: 'Run `npm run check:secrets` and resolve flagged secrets or add to allowlist',
+    };
   }
 }
 
@@ -113,29 +283,138 @@ function checkCompiledAdapters(projectDir) {
 }
 
 function checkLockfileIntegrity(projectDir) {
-  const lockPath = path.join(projectDir, '.agents', 'contextos.lock.json');
-  if (!fs.existsSync(lockPath)) {
-    return { ok: true, exists: false, isError: false, message: 'none (not generated yet)' };
+  const v2Path = path.join(projectDir, '.agents', 'lockfile.v2.json');
+  const v1Path = path.join(projectDir, '.agents', 'contextos.lock.json');
+  const hasV2 = fs.existsSync(v2Path);
+  const hasV1 = fs.existsSync(v1Path);
+
+  if (!hasV2 && !hasV1) {
+    return {
+      id: 'lockfile',
+      status: STATUS.WARN,
+      ok: true,
+      exists: false,
+      isError: false,
+      message: 'none (not generated yet)',
+      remediation: 'Run `contextos export all` or `contextos doctor --fix` to generate lockfile',
+    };
   }
+
+  // 1. Check Lockfile v2 if present
+  if (hasV2) {
+    try {
+      const raw = fs.readFileSync(v2Path, 'utf8');
+      const data = JSON.parse(raw);
+      const lockfileManager = new LockfileV2Manager(projectDir);
+      lockfileManager.validate(data);
+      const count = Object.keys(data.managedFiles || {}).length;
+      return {
+        id: 'lockfile',
+        status: STATUS.PASS,
+        ok: true,
+        exists: true,
+        isError: false,
+        message: `valid (v${data.schemaVersion}, rev ${data.revision}, ${count} managed files)`,
+        remediation: null,
+      };
+    } catch (err) {
+      return {
+        id: 'lockfile',
+        status: STATUS.FAIL,
+        ok: false,
+        exists: true,
+        isError: true,
+        error: `Lockfile v2 is corrupted or invalid: ${err.message}`,
+        remediation: 'Run `contextos doctor --fix` to regenerate valid Lockfile v2',
+      };
+    }
+  }
+
+  // 2. Check Lockfile v1
   try {
-    const raw = fs.readFileSync(lockPath, 'utf8');
+    const raw = fs.readFileSync(v1Path, 'utf8');
     const data = JSON.parse(raw);
     if (!data || typeof data !== 'object') {
-      return { ok: false, exists: true, isError: true, error: 'Lockfile JSON root is not an object' };
+      return {
+        id: 'lockfile',
+        status: STATUS.FAIL,
+        ok: false,
+        exists: true,
+        isError: true,
+        error: 'Lockfile JSON root is not an object',
+        remediation: 'Run `contextos doctor --fix` to rebuild lockfile',
+      };
     }
     if (!data.schemaVersion || typeof data.schemaVersion !== 'number') {
-      return { ok: false, exists: true, isError: true, error: 'Lockfile missing valid schemaVersion' };
+      return {
+        id: 'lockfile',
+        status: STATUS.FAIL,
+        ok: false,
+        exists: true,
+        isError: true,
+        error: 'Lockfile missing valid schemaVersion',
+        remediation: 'Run `contextos doctor --fix` to rebuild lockfile',
+      };
     }
-    if (!data.managedFiles || typeof data.managedFiles !== 'object') {
-      return { ok: false, exists: true, isError: true, error: 'Lockfile missing managedFiles map' };
+    if (!data.managedFiles && !data.files) {
+      return {
+        id: 'lockfile',
+        status: STATUS.FAIL,
+        ok: false,
+        exists: true,
+        isError: true,
+        error: 'Lockfile missing managedFiles map',
+        remediation: 'Run `contextos doctor --fix` to rebuild lockfile',
+      };
     }
-    const count = Object.keys(data.managedFiles).length;
-    return { ok: true, exists: true, isError: false, message: `valid (v${data.schemaVersion}, ${count} managed files)` };
+    const count = Object.keys(data.managedFiles || data.files || {}).length;
+    return {
+      id: 'lockfile',
+      status: STATUS.PASS,
+      ok: true,
+      exists: true,
+      isError: false,
+      message: `valid (v${data.schemaVersion}, ${count} managed files)`,
+      remediation: null,
+    };
   } catch (err) {
-    return { ok: false, exists: true, isError: true, error: `Lockfile is corrupted JSON: ${err.message}` };
+    return {
+      id: 'lockfile',
+      status: STATUS.FAIL,
+      ok: false,
+      exists: true,
+      isError: true,
+      error: `Lockfile is corrupted JSON: ${err.message}`,
+      remediation: 'Run `contextos doctor --fix` to rebuild lockfile',
+    };
   }
 }
 
+function checkTransactions(projectDir) {
+  try {
+    const pending = JournaledTransaction.listPending(projectDir);
+    if (pending.length > 0) {
+      return {
+        id: 'incomplete_transactions',
+        status: STATUS.RECOVERY_REQUIRED,
+        ok: false,
+        error: `RECOVERY_REQUIRED: Found ${pending.length} incomplete transaction(s).`,
+        pending,
+        remediation: 'Run: contextos recover --list',
+      };
+    }
+  } catch {
+    // Best-effort
+  }
+  return {
+    id: 'incomplete_transactions',
+    status: STATUS.PASS,
+    ok: true,
+    message: 'Clean (0 uncommitted transaction journals)',
+    remediation: null,
+  };
+}
+
 function checkAdapterIntegrity(projectDir) {
   const errors = [];
   const filesToCheck = [
@@ -149,10 +428,10 @@ function checkAdapterIntegrity(projectDir) {
       try {
         const stat = fs.statSync(f);
         if (stat.size === 0) {
-          errors.push(`Adapter file ${path.relative(projectDir, f).replace(/\\/g, '/')} is empty (0 bytes)`);
+          errors.push(`Adapter file ${toPosix(path.relative(projectDir, f))} is empty (0 bytes)`);
         }
       } catch {
-        errors.push(`Adapter file ${path.relative(projectDir, f).replace(/\\/g, '/')} is unreadable`);
+        errors.push(`Adapter file ${toPosix(path.relative(projectDir, f))} is unreadable`);
       }
     }
   }
@@ -170,13 +449,20 @@ function checkAdapterIntegrity(projectDir) {
     } catch {}
   }
 
-  return { ok: errors.length === 0, errors };
+  return {
+    id: 'adapter_integrity',
+    status: errors.length === 0 ? STATUS.PASS : STATUS.FAIL,
+    ok: errors.length === 0,
+    errors,
+    message: errors.length === 0 ? 'All compiled adapter files are structurally intact' : `${errors.length} corrupt adapter file(s)`,
+    remediation: errors.length === 0 ? null : 'Run `contextos export all` to re-render clean adapters',
+  };
 }
 
 function checkSymlinks(projectDir) {
   const errors = [];
   const targetDir = path.join(projectDir, '.agents');
-  if (!fs.existsSync(targetDir)) return { ok: true, errors: [] };
+  if (!fs.existsSync(targetDir)) return { ok: true, errors: [], status: STATUS.PASS };
 
   function scan(current) {
     let entries;
@@ -191,19 +477,304 @@ function checkSymlinks(projectDir) {
         const lstat = fs.lstatSync(full);
         if (lstat.isSymbolicLink()) {
           if (!fs.existsSync(full)) {
-            errors.push(`Broken symlink: ${path.relative(projectDir, full).replace(/\\/g, '/')}`);
+            errors.push(`Broken symlink: ${toPosix(path.relative(projectDir, full))}`);
           }
         } else if (lstat.isDirectory()) {
           scan(full);
         }
       } catch {
-        errors.push(`Cannot stat file: ${path.relative(projectDir, full).replace(/\\/g, '/')}`);
+        errors.push(`Cannot stat file: ${toPosix(path.relative(projectDir, full))}`);
       }
     }
   }
 
   scan(targetDir);
-  return { ok: errors.length === 0, errors };
+  return {
+    id: 'symlinks',
+    status: errors.length === 0 ? STATUS.PASS : STATUS.FAIL,
+    ok: errors.length === 0,
+    errors,
+    message: errors.length === 0 ? '0 broken symlinks' : `${errors.length} broken symlink(s)`,
+    remediation: errors.length === 0 ? null : 'Remove or re-point broken symlinks in .agents/',
+  };
+}
+
+function checkMcpHandshake(projectDir) {
+  const mcpServerPath = path.join(projectDir, '.agents', 'mcp', 'server.mjs');
+  if (!fs.existsSync(mcpServerPath)) {
+    return {
+      id: 'mcp_handshake',
+      status: STATUS.SKIP,
+      ok: true,
+      message: 'Optional MCP Bridge not installed.',
+      remediation: 'Install separately: npm install --save-dev @contextos/mcp',
+    };
+  }
+
+  try {
+    const syntaxCheck = execFileSync(process.execPath, ['--check', mcpServerPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return {
+      id: 'mcp_handshake',
+      status: STATUS.PASS,
+      ok: true,
+      message: 'server.mjs syntax and execution environment verified',
+      remediation: null,
+    };
+  } catch (err) {
+    return {
+      id: 'mcp_handshake',
+      status: STATUS.FAIL,
+      ok: false,
+      message: `MCP server syntax failure: ${err.message}`,
+      remediation: 'Rebuild MCP server bundle via `node scripts/build-mcp.js`',
+    };
+  }
+}
+
+function checkSandboxAvailability() {
+  try {
+    const stdout = execFileSync('docker', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return {
+      id: 'sandbox_availability',
+      status: STATUS.PASS,
+      ok: true,
+      message: `OCI Sandbox available (${stdout.trim()})`,
+      remediation: null,
+    };
+  } catch (err) {
+    try {
+      const podmanOut = execFileSync('podman', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      return {
+        id: 'sandbox_availability',
+        status: STATUS.PASS,
+        ok: true,
+        message: `OCI Sandbox available (${podmanOut.trim()})`,
+        remediation: null,
+      };
+    } catch {
+      return {
+        id: 'sandbox_availability',
+        status: STATUS.WARN,
+        ok: true,
+        message: 'OCI Sandbox (Docker/Podman) not found. Executions will fallback to host-unsafe mode.',
+        remediation: 'Install Docker or Podman to enable secure isolated execution',
+      };
+    }
+  }
+}
+
+function checkClaimEvidence(projectDir) {
+  const claimsPath = path.join(projectDir, 'benchmarks', 'claims.json');
+  if (!fs.existsSync(claimsPath)) {
+    return {
+      id: 'claim_evidence',
+      status: STATUS.SKIP,
+      ok: true,
+      message: 'No claims.json found (benchmarks/claims.json)',
+      remediation: null,
+    };
+  }
+
+  try {
+    const claimsData = JSON.parse(fs.readFileSync(claimsPath, 'utf8'));
+    let missingEvidence = 0;
+    const claims = claimsData.claims || [];
+    for (const claim of claims) {
+      if (claim.evidenceArtifact) {
+        const artifactPath = path.join(projectDir, claim.evidenceArtifact);
+        if (!fs.existsSync(artifactPath)) {
+          missingEvidence++;
+        }
+      }
+    }
+    
+    if (missingEvidence > 0) {
+      return {
+        id: 'claim_evidence',
+        status: STATUS.FAIL,
+        ok: false,
+        message: `${missingEvidence} claim(s) missing evidence artifact(s)`,
+        remediation: 'Run Benchmark v2 protocol to regenerate claim evidence',
+      };
+    }
+
+    return {
+      id: 'claim_evidence',
+      status: STATUS.PASS,
+      ok: true,
+      message: `All ${claims.length} claim(s) have verified evidence artifacts`,
+      remediation: null,
+    };
+  } catch (e) {
+    return {
+      id: 'claim_evidence',
+      status: STATUS.FAIL,
+      ok: false,
+      message: `Failed to parse claims.json: ${e.message}`,
+      remediation: 'Fix JSON syntax in benchmarks/claims.json',
+    };
+  }
+}
+
+function checkProjectLock(projectDir) {
+  try {
+    const lock = new ProjectMutationLock(projectDir);
+    const payload = lock.inspect();
+    
+    if (payload) {
+      const isAlive = isPidAlive(payload.pid);
+      if (!isAlive) {
+        return {
+          id: 'project_lock',
+          status: STATUS.WARN,
+          ok: true,
+          message: `Stale project mutation lock found (PID ${payload.pid} is dead)`,
+          remediation: 'Run `contextos doctor --fix` to clear stale locks',
+        };
+      }
+      return {
+        id: 'project_lock',
+        status: STATUS.WARN,
+        ok: true,
+        message: `Project mutation lock is currently held (PID ${payload.pid})`,
+        remediation: 'Wait for the current operation to finish',
+      };
+    }
+    return {
+      id: 'project_lock',
+      status: STATUS.PASS,
+      ok: true,
+      message: 'Project mutation lock is clean',
+      remediation: null,
+    };
+  } catch (e) {
+    return {
+      id: 'project_lock',
+      status: STATUS.UNVERIFIED,
+      ok: true,
+      message: `Project lock status unverified: ${e.message}`,
+      remediation: null,
+    };
+  }
+}
+
+function checkDriftStatus(projectDir) {
+  try {
+    const { detectDrift } = require('./adapters/drift-detector.js');
+    const drift = detectDrift(projectDir);
+    if (drift.isDrifted) {
+      const summaryParts = Object.entries(drift.counts)
+        .filter(([, count]) => count > 0)
+        .map(([state, count]) => `${state}: ${count}`);
+
+      return {
+        id: 'drift_status',
+        status: STATUS.WARN,
+        ok: true,
+        isDrifted: true,
+        message: `Output drift detected (${summaryParts.join(', ')})`,
+        remediation: 'Run `contextos export all` to synchronize generated adapters with current skills',
+        drift,
+      };
+    }
+    return {
+      id: 'drift_status',
+      status: STATUS.PASS,
+      ok: true,
+      isDrifted: false,
+      message: 'All generated adapter files match current source skills and profile',
+      remediation: null,
+    };
+  } catch {
+    return {
+      id: 'drift_status',
+      status: STATUS.UNVERIFIED,
+      ok: true,
+      message: 'Drift detection unverified',
+      remediation: null,
+    };
+  }
+}
+
+function isContextOSDevRepo(projectDir) {
+  try {
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return false;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.name === 'contextos-agents' || pkg.name === 'contextos';
+  } catch {
+    return false;
+  }
+}
+
+function checkModuleExecution(projectDir) {
+  const errors = [];
+
+  // Check CanonicalResolver
+  try {
+    const resolverPath = path.join(projectDir, '.agents', 'resolver', 'canonical-resolver.js');
+    if (fs.existsSync(resolverPath)) {
+      const resolver = require(resolverPath);
+      if (!resolver || typeof resolver.CanonicalResolver !== 'function') {
+        errors.push('CanonicalResolver is not exported correctly');
+      }
+    } else {
+      errors.push('.agents/resolver/canonical-resolver.js missing');
+    }
+  } catch (err) {
+    errors.push(`CanonicalResolver import failed: ${err.message}`);
+  }
+
+  // Check RuleCatalog
+  try {
+    const rulesPath = path.join(projectDir, '.agents', 'rules', 'rule-catalog.js');
+    if (fs.existsSync(rulesPath)) {
+      const rules = require(rulesPath);
+      if (!rules || typeof rules.RuleCatalog !== 'function') {
+        errors.push('RuleCatalog is not exported correctly');
+      }
+    } else {
+      errors.push('.agents/rules/rule-catalog.js missing');
+    }
+  } catch (err) {
+    errors.push(`RuleCatalog import failed: ${err.message}`);
+  }
+
+  // Check ManifestCompiler
+  try {
+    const compilerPath = path.join(projectDir, '.agents', 'compiler', 'manifest-compiler.js');
+    if (fs.existsSync(compilerPath)) {
+      const compiler = require(compilerPath);
+      if (!compiler || typeof compiler.ManifestCompiler !== 'function') {
+        errors.push('ManifestCompiler is not exported correctly');
+      }
+    } else {
+      errors.push('.agents/compiler/manifest-compiler.js missing');
+    }
+  } catch (err) {
+    errors.push(`ManifestCompiler import failed: ${err.message}`);
+  }
+
+  if (errors.length > 0) {
+    return {
+      id: 'module_execution',
+      status: STATUS.FAIL,
+      ok: false,
+      message: errors.join('; '),
+      errors,
+      remediation: 'Reinstall package via `npx contextos-agents init --force` to restore core modules',
+    };
+  }
+
+  return {
+    id: 'module_execution',
+    status: STATUS.PASS,
+    ok: true,
+    message: 'all core modules verified (resolver, rules, compiler)',
+    remediation: null,
+  };
 }
 
 function inspectSkills(projectDir, activeProfile) {
@@ -233,16 +804,119 @@ function inspectSkills(projectDir, activeProfile) {
   };
 }
 
+/**
+ * Executes doctor --fix safe remediation actions.
+ */
+function applyDoctorFix(projectDir = process.cwd(), options = {}) {
+  const results = [];
+
+  // 1. Recompile clean generated adapters
+  try {
+    const { renderAdapters, applyArtifacts } = require('./adapters/pure-compiler.js');
+    const rendered = renderAdapters(projectDir, 'all');
+    const applyRes = applyArtifacts(projectDir, rendered.artifacts, { command: 'doctor --fix' });
+    results.push(`✓ Recompiled all adapters (${applyRes.appliedCount} files updated, tx: ${applyRes.txId})`);
+  } catch (err) {
+    results.push(`✗ Could not recompile adapters: ${err.message}`);
+  }
+
+  // 2. Clean completed transaction logs older than 1 hour
+  try {
+    const txDir = path.join(projectDir, '.agents', '.contextos', 'transactions');
+    if (fs.existsSync(txDir)) {
+      let cleanedCount = 0;
+      const now = Date.now();
+      for (const entry of fs.readdirSync(txDir)) {
+        const fullEntry = path.join(txDir, entry);
+        const journalPath = path.join(fullEntry, 'journal.json');
+        if (fs.existsSync(journalPath)) {
+          try {
+            const journal = JSON.parse(fs.readFileSync(journalPath, 'utf8'));
+            if (journal.status === 'COMMITTED' || journal.status === 'ROLLED_BACK') {
+              const ageMs = now - (journal.committedAt || journal.startedAt || 0);
+              if (ageMs > 3600000) {
+                fs.rmSync(fullEntry, { recursive: true, force: true });
+                cleanedCount++;
+              }
+            }
+          } catch {}
+        }
+      }
+      if (cleanedCount > 0) {
+        results.push(`✓ Pruned ${cleanedCount} completed transaction journal(s)`);
+      }
+    }
+  } catch {}
+
+  // 3. Clear stale project mutation locks
+  try {
+    const { ProjectMutationLock, isPidAlive } = require('./filesystem/index.js');
+    const lock = new ProjectMutationLock(projectDir);
+    const payload = lock.inspect();
+    if (payload && !isPidAlive(payload.pid)) {
+      if (fs.existsSync(lock.lockPath)) {
+        fs.unlinkSync(lock.lockPath);
+        results.push(`✓ Pruned stale project mutation lock (PID ${payload.pid})`);
+      }
+    }
+  } catch {}
+
+  // 4. Clear temporary probe/error files
+  try {
+    const errLog = path.join(projectDir, '.agents', '.contextos', 'watch-error.json');
+    if (fs.existsSync(errLog)) {
+      fs.unlinkSync(errLog);
+      results.push('✓ Cleared stale watch error log');
+    }
+  } catch {}
+
+  return results;
+}
+
+/**
+ * Main entrypoint for ContextOS Doctor v2.
+ */
 function runDoctor(projectDir = process.cwd(), options = {}) {
   const version = (() => {
     try {
-      return require('../package.json').version;
+      const parentPkgPath = path.join(__dirname, '..', 'package.json');
+      if (fs.existsSync(parentPkgPath)) {
+        const parentPkg = JSON.parse(fs.readFileSync(parentPkgPath, 'utf8'));
+        if (parentPkg.name === 'contextos-agents' || parentPkg.name === 'contextos') {
+          return parentPkg.version;
+        }
+      }
+      const lockfileV2Path = path.join(projectDir, '.agents', 'lockfile.v2.json');
+      if (fs.existsSync(lockfileV2Path)) {
+        const lf = JSON.parse(fs.readFileSync(lockfileV2Path, 'utf8'));
+        if (lf.package && lf.package.compilerVersion) return lf.package.compilerVersion;
+      }
+      const lockfilePath = path.join(projectDir, '.agents', 'lockfile.json');
+      if (fs.existsSync(lockfilePath)) {
+        const lf = JSON.parse(fs.readFileSync(lockfilePath, 'utf8'));
+        if (lf.generator && lf.generator.version) return lf.generator.version;
+        if (lf.version) return lf.version;
+      }
+      return '2.0.0';
     } catch {
-      return '1.7.0';
+      return '2.0.0';
     }
   })();
 
   const isJson = Boolean(options.json);
+
+  // If --fix requested, run safe remediation first
+  let fixResults = [];
+  if (options.fix) {
+    fixResults = applyDoctorFix(projectDir, options);
+    if (!isJson) {
+      console.log('\n[ContextOS Doctor --fix] Running automated remediations:');
+      for (const res of fixResults) console.log(`  ${res}`);
+      console.log('');
+    }
+  }
+
+  const checks = [];
   const errors = [];
   const warnings = [];
 
@@ -252,59 +926,135 @@ function runDoctor(projectDir = process.cwd(), options = {}) {
     errors.push('.agents/ directory missing (run: npx contextos-agents init)');
   }
 
-  const nodeCheck = checkNodeVersion();
-  if (!nodeCheck.ok) {
-    errors.push(nodeCheck.message);
+  const moduleExecCheck = hasAgents ? checkModuleExecution(projectDir) : {
+    id: 'module_execution',
+    status: STATUS.FAIL,
+    ok: false,
+    message: '.agents directory missing',
+    remediation: 'Run: npx contextos-agents init',
+  };
+  checks.push(moduleExecCheck);
+  if (!moduleExecCheck.ok) {
+    errors.push(moduleExecCheck.message);
   }
 
+  const nodeCheck = checkNodeVersion();
+  checks.push(nodeCheck);
+  if (!nodeCheck.ok) errors.push(nodeCheck.message);
+  else if (nodeCheck.status === STATUS.WARN) warnings.push(nodeCheck.message);
+
+  const gitCheck = checkGitVersion();
+  checks.push(gitCheck);
+  if (!gitCheck.ok) errors.push(gitCheck.message);
+
+  const fsCheck = checkFilesystemPermissions(projectDir);
+  checks.push(fsCheck);
+  if (!fsCheck.ok) errors.push(fsCheck.message);
+
   const lockfileCheck = checkLockfileIntegrity(projectDir);
-  if (!lockfileCheck.ok) {
-    errors.push(lockfileCheck.error);
-  } else if (!lockfileCheck.exists && hasAgents) {
-    warnings.push('Lockfile missing (.agents/contextos.lock.json)');
-  }
+  checks.push(lockfileCheck);
+  if (!lockfileCheck.ok) errors.push(lockfileCheck.error || lockfileCheck.message);
+  else if (lockfileCheck.status === STATUS.WARN) warnings.push(lockfileCheck.message);
+
+  const txCheck = checkTransactions(projectDir);
+  checks.push(txCheck);
+  if (!txCheck.ok) errors.push(txCheck.error);
 
   const adapterCheck = checkAdapterIntegrity(projectDir);
-  if (!adapterCheck.ok) {
-    errors.push(...adapterCheck.errors);
-  }
+  checks.push(adapterCheck);
+  if (!adapterCheck.ok) errors.push(...adapterCheck.errors);
 
   const symlinkCheck = checkSymlinks(projectDir);
-  if (!symlinkCheck.ok) {
-    errors.push(...symlinkCheck.errors);
-  }
+  checks.push(symlinkCheck);
+  if (!symlinkCheck.ok) errors.push(...symlinkCheck.errors);
+
+  const driftCheck = checkDriftStatus(projectDir);
+  checks.push(driftCheck);
+  if (driftCheck.status === STATUS.WARN) warnings.push(driftCheck.message);
 
   const activeProfile = hasAgents ? profiles.getActiveProfile(projectDir) : null;
   const skillsInfo = inspectSkills(projectDir, activeProfile);
   const compiledAdapters = checkCompiledAdapters(projectDir);
 
-  const mcpServerPath = path.join(projectDir, '.agents', 'mcp', 'server.mjs');
-  const hasMcp = fs.existsSync(mcpServerPath);
+  const mcpCheck = checkMcpHandshake(projectDir);
+  checks.push(mcpCheck);
+  if (!mcpCheck.ok) errors.push(mcpCheck.message);
 
   const hookCheck = checkPreCommitHook(projectDir);
+  checks.push(hookCheck);
+  if (hookCheck.status === STATUS.WARN) warnings.push(hookCheck.message);
+
   const secretCheck = checkSecretScanner(projectDir);
+  checks.push(secretCheck);
+  if (!secretCheck.ok) {
+    if (secretCheck.status === STATUS.WARN) warnings.push(secretCheck.message);
+    else errors.push(secretCheck.message);
+  }
+
+  const sandboxCheck = checkSandboxAvailability();
+  checks.push(sandboxCheck);
+  if (sandboxCheck.status === STATUS.WARN) warnings.push(sandboxCheck.message);
+
+  const claimCheck = checkClaimEvidence(projectDir);
+  checks.push(claimCheck);
+  if (!claimCheck.ok) errors.push(claimCheck.message);
+  else if (claimCheck.status === STATUS.SKIP) warnings.push(claimCheck.message);
+
+  const projectLockCheck = checkProjectLock(projectDir);
+  checks.push(projectLockCheck);
+  if (projectLockCheck.status === STATUS.WARN) warnings.push(projectLockCheck.message);
+
   const stack = profiles.detectStack(projectDir);
 
-  const ok = errors.length === 0;
+  // Determine overall status
+  let overallStatus = STATUS.PASS;
+  if (txCheck.status === STATUS.RECOVERY_REQUIRED) {
+    overallStatus = STATUS.RECOVERY_REQUIRED;
+  } else if (errors.length > 0) {
+    overallStatus = STATUS.FAIL;
+  } else if (warnings.length > 0) {
+    overallStatus = STATUS.WARN;
+  }
+
+  if (options.strict && warnings.length > 0) {
+    overallStatus = STATUS.FAIL;
+  }
+
+  const ok = overallStatus === STATUS.PASS || overallStatus === STATUS.WARN;
 
   if (isJson) {
     const report = {
+      schemaVersion: '2.0.0',
+      status: overallStatus,
       ok,
       version,
+      timestamp: new Date().toISOString(),
       errors,
       warnings,
+      checks,
       hasAgents,
       nodeOk: nodeCheck.ok,
       activeProfile,
       skillsInfo,
       compiledAdapters,
-      hasMcp,
+      hasMcp: mcpCheck.ok && mcpCheck.status === STATUS.PASS,
       hookCheck,
       secretCheck,
       lockfileCheck,
       adapterCheck,
       symlinkCheck,
+      driftCheck,
+      sandboxCheck,
+      claimCheck,
+      projectLockCheck,
       stack,
+      summary: {
+        total: checks.length,
+        pass: checks.filter(c => c.status === STATUS.PASS).length,
+        warn: checks.filter(c => c.status === STATUS.WARN).length,
+        fail: checks.filter(c => c.status === STATUS.FAIL).length,
+        recovery: checks.filter(c => c.status === STATUS.RECOVERY_REQUIRED).length,
+      },
     };
     console.log(JSON.stringify(report, null, 2));
     if (options.exitOnError !== false && !ok && require.main === module) {
@@ -314,17 +1064,21 @@ function runDoctor(projectDir = process.cwd(), options = {}) {
   }
 
   console.log('\n┌─────────────────────────────────────────────────────────────┐');
-  console.log(`│  ContextOS Doctor — Project Health Check  v${version.padEnd(16)}│`);
+  console.log(`│  ContextOS Doctor v2 — Project Health Check  v${version.padEnd(14)}│`);
   console.log('├─────────────────────────────────────────────────────────────┤');
   console.log('│                                                             │');
 
-  // .agents directory
   if (hasAgents) {
     console.log('│  ✓ .agents/ directory found                                 │');
   } else {
     console.log('│  ✗ .agents/ directory missing (run: npx contextos-agents)    │');
   }
 
+  // Execution check
+  const execIcon = moduleExecCheck.ok ? '✓' : '✗';
+  const execStr = `Core modules: ${moduleExecCheck.message}`;
+  console.log(`│  ${execIcon} ${execStr.slice(0, 58).padEnd(58)}│`);
+
   // Node version
   const nodeIcon = nodeCheck.ok ? '✓' : '✗';
   console.log(`│  ${nodeIcon} ${nodeCheck.message.padEnd(58)}│`);
@@ -365,21 +1119,37 @@ function runDoctor(projectDir = process.cwd(), options = {}) {
   console.log(`│  ${symIcon} ${symStr.padEnd(58)}│`);
 
   // MCP
-  if (hasMcp) {
+  if (mcpCheck.status === STATUS.PASS) {
     console.log('│  ✓ MCP server: installed (.agents/mcp/server.mjs)           │');
   } else {
-    console.log('│  • MCP server: not installed (run: contextos setup-mcp)     │');
+    console.log('│  • MCP server: not installed (run: npm i -D @contextos/mcp) │');
   }
 
-  // Security
+  // Pre-commit hook
   const hookIcon = hookCheck.ok ? '✓' : '•';
   const hookStr = `Pre-commit hook: ${hookCheck.message}`;
   console.log(`│  ${hookIcon} ${hookStr.padEnd(58)}│`);
 
-  const secretIcon = secretCheck.ok ? '✓' : '✗';
+  // Secret scanner
+  const secretIcon = secretCheck.ok ? '✓' : (secretCheck.status === STATUS.WARN ? '•' : '✗');
   const secretStr = `Secret scanner: ${secretCheck.message}`;
   console.log(`│  ${secretIcon} ${secretStr.padEnd(58)}│`);
 
+  // Sandbox
+  const sandboxIcon = sandboxCheck.status === STATUS.PASS ? '✓' : '•';
+  const sandboxStr = `Sandbox: ${sandboxCheck.message}`;
+  console.log(`│  ${sandboxIcon} ${sandboxStr.slice(0, 58).padEnd(58)}│`);
+
+  // Claims Evidence
+  const claimIcon = claimCheck.status === STATUS.PASS ? '✓' : (claimCheck.status === STATUS.SKIP ? '•' : '✗');
+  const claimStr = `Claims evidence: ${claimCheck.message}`;
+  console.log(`│  ${claimIcon} ${claimStr.slice(0, 58).padEnd(58)}│`);
+
+  // Project Mutation Lock
+  const lockStateIcon = projectLockCheck.status === STATUS.PASS ? '✓' : (projectLockCheck.status === STATUS.WARN ? '•' : '✗');
+  const lockStateStr = `Mutation lock: ${projectLockCheck.message}`;
+  console.log(`│  ${lockStateIcon} ${lockStateStr.slice(0, 58).padEnd(58)}│`);
+
   console.log('│                                                             │');
   console.log('├─────────────────────────────────────────────────────────────┤');
   console.log('│  Project Stack & Profile Recommendations                    │');
@@ -416,20 +1186,27 @@ function runDoctor(projectDir = process.cwd(), options = {}) {
   }
 
   const result = {
+    schemaVersion: '2.0.0',
+    status: overallStatus,
     ok,
     errors,
     warnings,
+    checks,
     hasAgents,
     nodeOk: nodeCheck.ok,
     activeProfile,
     skillsInfo,
     compiledAdapters,
-    hasMcp,
+    hasMcp: mcpCheck.ok && mcpCheck.status === STATUS.PASS,
     hookCheck,
     secretCheck,
     lockfileCheck,
     adapterCheck,
     symlinkCheck,
+    driftCheck,
+    sandboxCheck,
+    claimCheck,
+    projectLockCheck,
     stack,
   };
 
@@ -446,13 +1223,25 @@ if (require.main === module) {
 }
 
 module.exports = {
+  STATUS,
   runDoctor,
+  applyDoctorFix,
   checkNodeVersion,
+  checkGitVersion,
+  checkFilesystemPermissions,
   checkPreCommitHook,
   checkSecretScanner,
   checkCompiledAdapters,
   checkLockfileIntegrity,
+  checkTransactions,
   checkAdapterIntegrity,
   checkSymlinks,
+  checkMcpHandshake,
+  checkDriftStatus,
+  checkSandboxAvailability,
+  checkClaimEvidence,
+  checkProjectLock,
+  checkModuleExecution,
+  isContextOSDevRepo,
   inspectSkills,
 };