tractatus/scripts/hook-validators/validate-file-write.js

#!/usr/bin/env node

/**
 * Hook Validator: File Write
 *
 * Runs BEFORE Write tool execution to enforce governance requirements.
 * This is architectural enforcement - AI cannot bypass this check.
 *
 * Checks:
 * 1. Pre-action validation (CSP, file type restrictions)
 * 2. Overwrite without read check (file exists but not read)
 * 3. CrossReferenceValidator (instruction conflicts)
 * 4. BoundaryEnforcer (values decisions)
 *
 * Exit codes:
 * 0 = PASS (allow write)
 * 1 = FAIL (block write)
 *
 * Copyright 2025 Tractatus Project
 * Licensed under Apache License 2.0
 */

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

const FILE_PATH = process.argv[2];
const SESSION_STATE_PATH = path.join(__dirname, '../../.claude/session-state.json');
const INSTRUCTION_HISTORY_PATH = path.join(__dirname, '../../.claude/instruction-history.json');

/**
 * Color output
 */
const colors = {
  reset: '\x1b[0m',
  green: '\x1b[32m',
  yellow: '\x1b[33m',
  red: '\x1b[31m',
  cyan: '\x1b[36m'
};

function log(message, color = 'reset') {
  console.log(`${colors[color]}${message}${colors.reset}`);
}

function error(message) {
  log(`  ✗ ${message}`, 'red');
}

function warning(message) {
  log(`  ⚠ ${message}`, 'yellow');
}

function success(message) {
  log(`  ✓ ${message}`, 'green');
}

/**
 * Check 1: Pre-action validation
 */
function runPreActionCheck() {
  try {
    // Determine action type
    let actionType = 'file-edit';

    // Run pre-action-check.js
    execSync(
      `node ${path.join(__dirname, '../pre-action-check.js')} ${actionType} "${FILE_PATH}" "Hook validation"`,
      { encoding: 'utf8', stdio: 'pipe' }
    );

    return { passed: true };
  } catch (err) {
    return {
      passed: false,
      reason: 'Pre-action check failed (CSP violation or file restriction)',
      output: err.stdout || err.message
    };
  }
}

/**
 * Check 2: Overwrite without read
 * CLAUDE.md requires reading files before writing (to avoid overwrites)
 */
function checkOverwriteWithoutRead() {
  if (!fs.existsSync(FILE_PATH)) {
    // New file - no risk of overwrite
    return { passed: true };
  }

  // File exists - this is an overwrite
  // In a real implementation, we'd check if the file was recently read
  // For now, we'll issue a warning but not block
  warning(`File exists - overwriting: ${FILE_PATH}`);
  warning(`Best practice: Read file before writing to avoid data loss`);

  return { passed: true };  // Warning only, not blocking
}

/**
 * Check 3: CrossReferenceValidator
 */
function checkInstructionConflicts() {
  try {
    if (!fs.existsSync(INSTRUCTION_HISTORY_PATH)) {
      return { passed: true, conflicts: [] };
    }

    const history = JSON.parse(fs.readFileSync(INSTRUCTION_HISTORY_PATH, 'utf8'));
    const activeInstructions = history.instructions?.filter(i => i.active) || [];

    const highPriorityInstructions = activeInstructions.filter(i => i.persistence === 'HIGH');

    if (highPriorityInstructions.length === 0) {
      return { passed: true, conflicts: [] };
    }

    const conflicts = highPriorityInstructions.filter(instruction => {
      if (instruction.context && typeof instruction.context === 'string') {
        return instruction.context.includes(FILE_PATH) ||
               FILE_PATH.includes(instruction.context);
      }
      return false;
    });

    if (conflicts.length > 0) {
      return {
        passed: false,
        reason: `Conflicts with ${conflicts.length} HIGH persistence instruction(s)`,
        conflicts: conflicts.map(c => ({
          id: c.id,
          instruction: c.instruction,
          quadrant: c.quadrant
        }))
      };
    }

    return { passed: true, conflicts: [] };
  } catch (err) {
    warning(`Could not check instruction conflicts: ${err.message}`);
    return { passed: true, conflicts: [] };
  }
}

/**
 * Check 4: BoundaryEnforcer - Values decisions
 */
function checkBoundaryViolation() {
  const valuesIndicators = [
    '/docs/values/',
    '/docs/ethics/',
    'privacy-policy',
    'code-of-conduct',
    'values.html',
    '/pluralistic-values'
  ];

  const isValuesContent = valuesIndicators.some(indicator =>
    FILE_PATH.toLowerCase().includes(indicator.toLowerCase())
  );

  if (isValuesContent) {
    return {
      passed: false,
      reason: 'File appears to contain values content - requires human approval',
      requiresHumanApproval: true
    };
  }

  return { passed: true };
}

/**
 * Update session state
 */
function updateSessionState() {
  try {
    if (fs.existsSync(SESSION_STATE_PATH)) {
      const sessionState = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
      sessionState.last_framework_activity = sessionState.last_framework_activity || {};
      sessionState.last_framework_activity.FileWriteHook = {
        timestamp: new Date().toISOString(),
        file: FILE_PATH,
        result: 'passed'
      };
      sessionState.last_updated = new Date().toISOString();
      fs.writeFileSync(SESSION_STATE_PATH, JSON.stringify(sessionState, null, 2));
    }
  } catch (err) {
    // Non-critical
  }
}

/**
 * Main validation
 */
async function main() {
  if (!FILE_PATH) {
    error('No file path provided');
    process.exit(1);
  }

  log(`\n🔍 Hook: Validating file write: ${FILE_PATH}`, 'cyan');

  // Check 1: Pre-action validation
  const preCheck = runPreActionCheck();
  if (!preCheck.passed) {
    error(preCheck.reason);
    if (preCheck.output) {
      console.log(preCheck.output);
    }
    process.exit(1);
  }
  success('Pre-action check passed');

  // Check 2: Overwrite without read
  const overwriteCheck = checkOverwriteWithoutRead();
  if (!overwriteCheck.passed) {
    error(overwriteCheck.reason);
    process.exit(1);
  }

  // Check 3: CrossReferenceValidator
  const conflicts = checkInstructionConflicts();
  if (!conflicts.passed) {
    error(conflicts.reason);
    conflicts.conflicts.forEach(c => {
      log(`    • ${c.id}: ${c.instruction} [${c.quadrant}]`, 'yellow');
    });
    process.exit(1);
  }
  success('No instruction conflicts detected');

  // Check 4: BoundaryEnforcer
  const boundary = checkBoundaryViolation();
  if (!boundary.passed) {
    error(boundary.reason);
    process.exit(1);
  }
  success('No boundary violations detected');

  // Update session state
  updateSessionState();

  success('File write validation complete\n');
  process.exit(0);
}

main().catch(err => {
  error(`Hook validation error: ${err.message}`);
  process.exit(1);
});