tractatus/scripts/hook-validators/validate-cultural-dna.js

#!/usr/bin/env node

/**
 * Cultural DNA Validator
 *
 * Enforces Tractatus cultural principles (inst_085-089) in public-facing content
 *
 * Rules:
 * - inst_085: Grounded Language Requirement
 * - inst_086: Honest Uncertainty Disclosure
 * - inst_087: One Approach Framing
 * - inst_088: Awakening Over Recruiting
 * - inst_089: Architectural Constraint Emphasis
 */

const fs = require('fs');
const path = require('path');

// File patterns that should be checked
const PUBLIC_FACING_PATTERNS = [
  /^docs\/outreach\//,
  /^docs\/implementation\//,
  /^public\/.*\.html$/,
  /^README\.md$/,
  /^docs\/.*\.md$/,
];

// Internal documentation that can be skipped
const INTERNAL_DOC_PATTERNS = [
  /^docs\/framework\//,
  /^docs\/governance\//,
  /^docs\/SESSION_/,
  /CLAUDE/,
  /internal/i,
  /^\.claude\//,
];

/**
 * Check if file is public-facing content that needs validation
 */
function isPublicFacing(filePath) {
  // Skip internal docs
  if (INTERNAL_DOC_PATTERNS.some(pattern => pattern.test(filePath))) {
    return false;
  }

  // Check if matches public-facing patterns
  return PUBLIC_FACING_PATTERNS.some(pattern => pattern.test(filePath));
}

/**
 * inst_085: Grounded Language Requirement
 * Detect abstract governance theory terms
 */
function checkGroundedLanguage(content, filePath) {
  const violations = [];

  const prohibitedTerms = [
    { term: 'comprehensive', context: 'comprehensive.*governance' },
    { term: 'holistic', context: 'holistic.*approach' },
    { term: 'best practices', context: 'best practices' },
    { term: 'ensures', context: 'ensures.*governance|ensures.*compliance|ensures.*safety' },
    { term: 'guarantees', context: 'guarantees.*' },
    { term: 'proven', context: 'proven.*framework|proven.*approach' },
  ];

  const lines = content.split('\n');

  for (const { term, context } of prohibitedTerms) {
    const regex = new RegExp(context, 'gi');

    lines.forEach((line, index) => {
      // Skip if in quoted example or code block
      if (line.trim().startsWith('❌') || line.trim().startsWith('```')) {
        return;
      }

      if (regex.test(line)) {
        violations.push({
          rule: 'inst_085',
          line: index + 1,
          term: term,
          excerpt: line.trim().substring(0, 80),
          message: `Use grounded operational language instead of abstract term "${term}"`,
          suggestion: `Replace with specific mechanisms: "blocks violations", "prevents exposure", "architectural constraints"`
        });
      }
    });
  }

  return violations;
}

/**
 * inst_086: Honest Uncertainty Disclosure
 * Detect certainty claims without uncertainty disclosure
 */
function checkHonestUncertainty(content, filePath) {
  const violations = [];

  const certaintyTerms = [
    { term: 'proven to prevent', required: 'scaling validation in progress' },
    { term: 'guarantees', required: 'we think|validation' },
    { term: 'total compliance', required: 'we think|finding out' },
    { term: 'completely prevents', required: 'development environment|validation' },
  ];

  const lines = content.split('\n');

  for (const { term, required } of certaintyTerms) {
    const termRegex = new RegExp(term, 'gi');
    const disclosureRegex = new RegExp(required, 'gi');

    lines.forEach((line, index) => {
      if (termRegex.test(line)) {
        // Check if disclosure appears nearby (within 2 lines)
        const context = lines.slice(Math.max(0, index - 2), index + 3).join(' ');

        if (!disclosureRegex.test(context)) {
          violations.push({
            rule: 'inst_086',
            line: index + 1,
            term: term,
            excerpt: line.trim().substring(0, 80),
            message: `Certainty claim "${term}" needs uncertainty disclosure`,
            suggestion: `Add: "we think it works but we're finding out" or "in development environment; scaling validation in progress"`
          });
        }
      }
    });
  }

  return violations;
}

/**
 * inst_087: One Approach Framing
 * Detect exclusive positioning language
 */
function checkOneApproachFraming(content, filePath) {
  const violations = [];

  const exclusiveTerms = [
    'the answer to',
    'the solution to',
    'the only way',
    'the framework for',
    'the right approach',
    'the best approach',
  ];

  const lines = content.split('\n');

  lines.forEach((line, index) => {
    // Skip examples
    if (line.trim().startsWith('❌') || line.trim().startsWith('```')) {
      return;
    }

    for (const term of exclusiveTerms) {
      const regex = new RegExp(term, 'gi');
      if (regex.test(line)) {
        violations.push({
          rule: 'inst_087',
          line: index + 1,
          term: term,
          excerpt: line.trim().substring(0, 80),
          message: `Exclusive positioning detected: "${term}"`,
          suggestion: `Use humble framing: "one possible approach", "an approach that could work", "we think this could work"`
        });
      }
    }
  });

  return violations;
}

/**
 * inst_088: Awakening Over Recruiting
 * Detect recruitment language
 */
function checkAwakeningLanguage(content, filePath) {
  const violations = [];

  const recruitmentTerms = [
    'join the movement',
    'become part of',
    'our community',
    'join us',
    'be part of the solution',
    'movement building',
    'supporting a movement',
  ];

  const lines = content.split('\n');

  lines.forEach((line, index) => {
    // Skip examples
    if (line.trim().startsWith('❌') || line.trim().startsWith('```')) {
      return;
    }

    for (const term of recruitmentTerms) {
      const regex = new RegExp(term, 'gi');
      if (regex.test(line)) {
        violations.push({
          rule: 'inst_088',
          line: index + 1,
          term: term,
          excerpt: line.trim().substring(0, 80),
          message: `Recruitment language detected: "${term}"`,
          suggestion: `Use awakening language: "understand the governance gap", "explore one approach", "see what's missing"`
        });
      }
    }
  });

  return violations;
}

/**
 * inst_089: Architectural Constraint Emphasis
 * Warn if mentioning training/prompting without architectural contrast
 */
function checkArchitecturalEmphasis(content, filePath) {
  const violations = [];

  // Skip measurement/BI documents
  if (/measurement|bi|roi|metric/i.test(filePath)) {
    return violations; // Not applicable
  }

  const behavioralTerms = [
    'better prompts',
    'improved guidelines',
    'training.*AI',
    'prompting.*approach',
  ];

  const architecturalContrast = [
    'architectural constraint',
    'structural mechanism',
    'more training prolongs the pain',
    'hope-based governance',
  ];

  const lines = content.split('\n');

  behavioralTerms.forEach(term => {
    const behavioralRegex = new RegExp(term, 'gi');

    lines.forEach((line, index) => {
      if (behavioralRegex.test(line)) {
        // Check if architectural contrast appears nearby (within 3 lines)
        const context = lines.slice(Math.max(0, index - 3), index + 4).join(' ');

        const hasContrast = architecturalContrast.some(contrast =>
          new RegExp(contrast, 'gi').test(context)
        );

        if (!hasContrast) {
          violations.push({
            rule: 'inst_089',
            line: index + 1,
            term: term,
            excerpt: line.trim().substring(0, 80),
            message: `Behavioral approach mentioned without architectural contrast`,
            suggestion: `Add contrast: "architectural constraints enforce governance; more training prolongs the pain" or "not prompts hoping for compliance"`
          });
        }
      }
    });
  });

  return violations;
}

/**
 * Validate file content against all cultural DNA rules
 */
function validateCulturalDNA(filePath, content) {
  if (!isPublicFacing(filePath)) {
    return { applicable: false, violations: [] };
  }

  const violations = [
    ...checkGroundedLanguage(content, filePath),
    ...checkHonestUncertainty(content, filePath),
    ...checkOneApproachFraming(content, filePath),
    ...checkAwakeningLanguage(content, filePath),
    ...checkArchitecturalEmphasis(content, filePath),
  ];

  return {
    applicable: true,
    violations,
  };
}

/**
 * CLI Interface
 */
function main() {
  const filePath = process.argv[2];

  if (!filePath) {
    console.error('Usage: node validate-cultural-dna.js <file-path>');
    process.exit(1);
  }

  if (!fs.existsSync(filePath)) {
    console.error(`File not found: ${filePath}`);
    process.exit(1);
  }

  const content = fs.readFileSync(filePath, 'utf8');
  const result = validateCulturalDNA(filePath, content);

  if (!result.applicable) {
    console.log(`✓ Cultural DNA check: Not applicable (internal documentation)`);
    process.exit(0);
  }

  if (result.violations.length === 0) {
    console.log(`✓ Cultural DNA check: PASSED (${filePath})`);
    process.exit(0);
  }

  // Report violations
  console.error(`\n❌ Cultural DNA Violations Found: ${filePath}\n`);
  console.error(`Found ${result.violations.length} violation(s):\n`);

  result.violations.forEach((v, index) => {
    console.error(`${index + 1}. [${v.rule}] Line ${v.line}: ${v.message}`);
    console.error(`   Term: "${v.term}"`);
    console.error(`   Context: "${v.excerpt}"`);
    console.error(`   💡 ${v.suggestion}\n`);
  });

  console.error(`\nCultural DNA Rules (inst_085-089) enforce Tractatus principles:`);
  console.error(`  • Grounded operational language (not abstract theory)`);
  console.error(`  • Honest uncertainty disclosure (not hype)`);
  console.error(`  • One approach framing (not exclusive positioning)`);
  console.error(`  • Awakening awareness (not recruiting)`);
  console.error(`  • Architectural constraints (not behavioral training)\n`);

  process.exit(1);
}

// Export for use in other validators
module.exports = {
  validateCulturalDNA,
  isPublicFacing,
};

// Run if called directly
if (require.main === module) {
  main();
}