@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/hierarchy-validator.js

@@ -0,0 +1,643 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { AGENT_HIERARCHY } from './agents/registry.js';
+
+/**
+ * HIERARCHY ENFORCEMENT GATE CHECK
+ *
+ * Problem: Boss Claude violated hierarchy twice by accepting direct worker reports
+ * without Boss-tier validation.
+ *
+ * Solution: Hard-code gate check that prompts "Which domain Boss validated this?"
+ * before accepting any worker agent results.
+ *
+ * Enforces: AGENT-HIERARCHY-CANON.md delegation rules
+ * - Worker → Boss Review → Meta-Boss Approval
+ * - Never Worker → Meta-Boss directly
+ */
+
+export class HierarchyValidator {
+  constructor() {
+    this.violations = [];
+    this.validations = [];
+  }
+
+  /**
+   * GATE CHECK: Enforces hierarchy before Boss Claude accepts work
+   *
+   * @param {Object} workResult - Result from an agent
+   * @param {string} workResult.agent - Agent name who did the work
+   * @param {string} workResult.task - Task description
+   * @param {Object} workResult.output - Work output
+   * @param {number} workResult.tokensUsed - Tokens consumed
+   * @returns {Promise<Object>} Validation result with approval status
+   */
+  async validateChain(workResult) {
+    const { agent, task, output, tokensUsed } = workResult;
+
+    // Check if this is a worker agent
+    const agentInfo = AGENT_HIERARCHY.workers[agent];
+
+    if (!agentInfo) {
+      // Not a worker agent - could be boss or meta-boss
+      return {
+        approved: true,
+        reason: 'Not a worker agent - hierarchy validation not required',
+        agent,
+        task
+      };
+    }
+
+    console.log(chalk.yellow('\n⚠️  HIERARCHY GATE CHECK TRIGGERED'));
+    console.log(chalk.dim('─'.repeat(80)));
+    console.log(chalk.white(`\nWorker Agent: ${chalk.bold(agent)}`));
+    console.log(chalk.white(`Task: ${chalk.dim(task)}`));
+    console.log(chalk.white(`Assigned Boss: ${chalk.cyan(agentInfo.boss)}`));
+    console.log(chalk.white(`Domain: ${chalk.green(agentInfo.domain)}`));
+    console.log(chalk.white(`Tokens Used: ${chalk.magenta(tokensUsed.toLocaleString())}`));
+
+    console.log(chalk.yellow('\n📋 HIERARCHY CANON REQUIREMENT:'));
+    console.log(chalk.dim('  Worker creates code → Boss reviews → Meta-Boss approves'));
+    console.log(chalk.red('  NEVER: Worker → Meta-Boss directly (skips boss review)'));
+
+    console.log(chalk.dim('\n─'.repeat(80)));
+
+    // HARD GATE: Ask Boss Claude which domain Boss validated this
+    const questions = [
+      {
+        type: 'list',
+        name: 'validationStatus',
+        message: chalk.bold('Which domain Boss validated this work?'),
+        choices: [
+          {
+            name: `✅ ${agentInfo.boss} reviewed and approved`,
+            value: 'boss_approved',
+            short: `${agentInfo.boss} approved`
+          },
+          {
+            name: `❌ No boss review yet (VIOLATION - must be reviewed first)`,
+            value: 'no_boss_review',
+            short: 'No review'
+          },
+          {
+            name: `🔄 Different boss reviewed this`,
+            value: 'different_boss',
+            short: 'Different boss'
+          }
+        ],
+        default: 1 // Default to violation to force conscious choice
+      }
+    ];
+
+    const answers = await inquirer.prompt(questions);
+
+    // Handle different validation scenarios
+    if (answers.validationStatus === 'boss_approved') {
+      // Require additional confirmation
+      const confirmQuestions = [
+        {
+          type: 'input',
+          name: 'reviewDetails',
+          message: chalk.cyan(`What security/quality issues did ${agentInfo.boss} check?`),
+          validate: (input) => {
+            if (input.length < 10) {
+              return 'Please provide specific review details (min 10 characters)';
+            }
+            return true;
+          }
+        },
+        {
+          type: 'confirm',
+          name: 'finalApproval',
+          message: chalk.green('Confirm: Boss review was thorough and complete?'),
+          default: false
+        }
+      ];
+
+      const confirmation = await inquirer.prompt(confirmQuestions);
+
+      if (!confirmation.finalApproval) {
+        return this._recordViolation(agent, task, 'Boss review incomplete');
+      }
+
+      // SUCCESS: Proper hierarchy followed
+      return this._recordValidation(agent, task, agentInfo.boss, confirmation.reviewDetails);
+    }
+
+    if (answers.validationStatus === 'no_boss_review') {
+      // VIOLATION: Worker output submitted directly to Meta-Boss
+      console.log(chalk.red('\n🚨 HIERARCHY VIOLATION DETECTED'));
+      console.log(chalk.red(`Worker agent "${agent}" submitted work without Boss review`));
+      console.log(chalk.yellow('\n📚 CANONICAL PROTOCOL:'));
+      console.log(chalk.dim(`  1. ${agent} creates work`));
+      console.log(chalk.dim(`  2. ${agentInfo.boss} reviews for domain security`));
+      console.log(chalk.dim(`  3. Boss Claude (Meta-Boss) does final approval`));
+      console.log(chalk.red(`\n❌ You attempted to skip step 2`));
+
+      const remedyQuestions = [
+        {
+          type: 'list',
+          name: 'remedy',
+          message: 'How do you want to proceed?',
+          choices: [
+            {
+              name: `🔄 Send to ${agentInfo.boss} for review (RECOMMENDED)`,
+              value: 'send_to_boss',
+              short: 'Send to boss'
+            },
+            {
+              name: `⚠️  Override: I will review this myself (logs violation)`,
+              value: 'override',
+              short: 'Override'
+            },
+            {
+              name: `❌ Reject: Start over with proper delegation`,
+              value: 'reject',
+              short: 'Reject'
+            }
+          ],
+          default: 0
+        }
+      ];
+
+      const remedy = await inquirer.prompt(remedyQuestions);
+
+      if (remedy.remedy === 'send_to_boss') {
+        console.log(chalk.green(`\n✅ Delegating to ${agentInfo.boss} for review...`));
+        return {
+          approved: false,
+          action: 'delegate_to_boss',
+          boss: agentInfo.boss,
+          agent,
+          task,
+          reason: 'Proper hierarchy enforcement - sending to boss for review'
+        };
+      }
+
+      if (remedy.remedy === 'override') {
+        const overrideQuestions = [
+          {
+            type: 'input',
+            name: 'justification',
+            message: chalk.yellow('Provide justification for override (will be logged):'),
+            validate: (input) => input.length >= 20 || 'Justification must be at least 20 characters'
+          }
+        ];
+
+        const override = await inquirer.prompt(overrideQuestions);
+        return this._recordViolation(agent, task, `Override: ${override.justification}`);
+      }
+
+      if (remedy.remedy === 'reject') {
+        console.log(chalk.red('\n❌ Work rejected - hierarchy violation'));
+        return {
+          approved: false,
+          action: 'reject',
+          agent,
+          task,
+          reason: 'Hierarchy violation - must follow canonical delegation protocol'
+        };
+      }
+    }
+
+    if (answers.validationStatus === 'different_boss') {
+      const bossQuestion = [
+        {
+          type: 'input',
+          name: 'actualBoss',
+          message: 'Which boss reviewed this?',
+        },
+        {
+          type: 'input',
+          name: 'reason',
+          message: `Why not ${agentInfo.boss} (the assigned boss)?`,
+          validate: (input) => input.length >= 10 || 'Please explain (min 10 characters)'
+        }
+      ];
+
+      const bossInfo = await inquirer.prompt(bossQuestion);
+
+      console.log(chalk.yellow(`\n⚠️  Non-standard boss assignment detected`));
+      console.log(chalk.dim(`Expected: ${agentInfo.boss}`));
+      console.log(chalk.dim(`Actual: ${bossInfo.actualBoss}`));
+      console.log(chalk.dim(`Reason: ${bossInfo.reason}`));
+
+      return this._recordValidation(agent, task, bossInfo.actualBoss, bossInfo.reason, true);
+    }
+  }
+
+  /**
+   * CANON RULE: Repository Boundary Check
+   * Ensures agents ONLY write to current repository, never to other repos
+   *
+   * @param {string} filePath - File path to validate
+   * @param {string} currentRepo - Current repository root path
+   * @returns {Promise<Object>} Validation result with boundary status
+   */
+  async checkRepoBoundary(filePath, currentRepo) {
+    // Normalize paths for comparison
+    const normalizedFilePath = filePath.replace(/^~/, process.env.HOME);
+    const normalizedRepo = currentRepo.replace(/^~/, process.env.HOME);
+
+    // Check if file is within current repo
+    const isWithinRepo = normalizedFilePath.startsWith(normalizedRepo);
+
+    if (!isWithinRepo) {
+      console.log(chalk.red('\n🚨 REPOSITORY BOUNDARY VIOLATION'));
+      console.log(chalk.dim('─'.repeat(80)));
+      console.log(chalk.white(`File Path: ${chalk.yellow(filePath)}`));
+      console.log(chalk.white(`Current Repo: ${chalk.cyan(currentRepo)}`));
+      console.log(chalk.red('\n❌ CANON RULE: Agents ONLY write in current repository'));
+      console.log(chalk.dim('Never write to other repositories'));
+
+      const questions = [
+        {
+          type: 'list',
+          name: 'action',
+          message: chalk.bold('Repository boundary violation detected. How to proceed?'),
+          choices: [
+            {
+              name: `❌ Reject write operation (RECOMMENDED)`,
+              value: 'reject',
+              short: 'Reject'
+            },
+            {
+              name: `⚠️  Override with justification (logs violation)`,
+              value: 'override',
+              short: 'Override'
+            }
+          ],
+          default: 0
+        }
+      ];
+
+      const answer = await inquirer.prompt(questions);
+
+      if (answer.action === 'reject') {
+        return {
+          allowed: false,
+          reason: 'Repository boundary violation - file outside current repo',
+          filePath,
+          currentRepo,
+          violation: true
+        };
+      }
+
+      // Override path - require justification
+      const justificationQuestion = [
+        {
+          type: 'input',
+          name: 'justification',
+          message: chalk.yellow('Provide justification for cross-repo write (will be logged):'),
+          validate: (input) => {
+            if (input.length < 30) {
+              return 'Justification must be at least 30 characters and explain why this is necessary';
+            }
+            return true;
+          }
+        }
+      ];
+
+      const justification = await inquirer.prompt(justificationQuestion);
+
+      // Record violation
+      this.violations.push({
+        timestamp: new Date().toISOString(),
+        type: 'repository_boundary',
+        filePath,
+        currentRepo,
+        justification: justification.justification,
+        severity: 'high'
+      });
+
+      console.log(chalk.yellow('\n⚠️  Cross-repo write override logged'));
+      console.log(chalk.dim(`Justification: ${justification.justification}`));
+
+      return {
+        allowed: true,
+        override: true,
+        reason: `Override: ${justification.justification}`,
+        filePath,
+        currentRepo,
+        violation: true
+      };
+    }
+
+    // File is within current repo - allowed
+    return {
+      allowed: true,
+      reason: 'File within current repository boundary',
+      filePath,
+      currentRepo,
+      violation: false
+    };
+  }
+
+  /**
+   * Quick gate check for interactive prompts during task execution
+   * Returns true if hierarchy is being followed, false if violation detected
+   */
+  async quickCheck(agentName) {
+    const agentInfo = AGENT_HIERARCHY.workers[agentName];
+
+    if (!agentInfo) {
+      return { valid: true, reason: 'Not a worker agent' };
+    }
+
+    console.log(chalk.yellow(`\n🔍 Quick Hierarchy Check: ${agentName}`));
+
+    const answer = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'hasBossReview',
+        message: `Has ${chalk.cyan(agentInfo.boss)} reviewed this work?`,
+        default: false
+      }
+    ]);
+
+    if (!answer.hasBossReview) {
+      console.log(chalk.red(`❌ Work from ${agentName} must be reviewed by ${agentInfo.boss} first`));
+      return {
+        valid: false,
+        reason: `Missing ${agentInfo.boss} review`,
+        requiredBoss: agentInfo.boss,
+        agent: agentName
+      };
+    }
+
+    return { valid: true, boss: agentInfo.boss };
+  }
+
+  /**
+   * Pre-task delegation check (enforces Rule #1: 10,000 Token Rule)
+   */
+  async checkDelegation(task, estimatedTokens, currentAgent = 'Boss Claude') {
+    if (estimatedTokens < 10000) {
+      // Under threshold - no delegation check needed
+      return { shouldDelegate: false, reason: 'Under 10k token threshold' };
+    }
+
+    console.log(chalk.blue('\n📊 DELEGATION ANALYSIS (Rule #1: 10,000 Token Rule)'));
+    console.log(chalk.dim('─'.repeat(80)));
+    console.log(chalk.white(`Task: ${task}`));
+    console.log(chalk.white(`Estimated Tokens: ${chalk.magenta(estimatedTokens.toLocaleString())}`));
+    console.log(chalk.white(`Current Agent: ${chalk.cyan(currentAgent)}`));
+
+    // Find best specialist
+    const specialist = this._findBestSpecialist(task);
+
+    if (specialist) {
+      const savings = Math.floor((1 - (specialist.estimatedTokens / estimatedTokens)) * 100);
+
+      console.log(chalk.green(`\n✅ Specialist Found: ${specialist.agent}`));
+      console.log(chalk.white(`Domain: ${specialist.domain}`));
+      console.log(chalk.white(`Estimated Tokens: ${chalk.magenta(specialist.estimatedTokens.toLocaleString())}`));
+      console.log(chalk.white(`Savings: ${chalk.green(savings + '%')}`));
+
+      const answer = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'decision',
+          message: 'Delegation recommended. What would you like to do?',
+          choices: [
+            {
+              name: `✅ Delegate to ${specialist.agent} (RECOMMENDED - saves ${savings}%)`,
+              value: 'delegate',
+              short: 'Delegate'
+            },
+            {
+              name: `⚠️  Override: I'll do it myself (requires justification)`,
+              value: 'override',
+              short: 'Override'
+            }
+          ],
+          default: 0
+        }
+      ]);
+
+      if (answer.decision === 'delegate') {
+        console.log(chalk.green(`\n✅ Delegating to ${specialist.agent}...`));
+        return {
+          shouldDelegate: true,
+          agent: specialist.agent,
+          estimatedSavings: savings,
+          reason: `Specialist can complete in ${specialist.estimatedTokens} tokens vs ${estimatedTokens}`
+        };
+      }
+
+      // Override path
+      const justification = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'reason',
+          message: chalk.yellow('Why override delegation? (will be logged):'),
+          validate: (input) => input.length >= 20 || 'Justification required (min 20 chars)'
+        }
+      ]);
+
+      console.log(chalk.yellow('\n⚠️  Delegation override logged'));
+
+      return {
+        shouldDelegate: false,
+        override: true,
+        specialist: specialist.agent,
+        wastedTokens: estimatedTokens - specialist.estimatedTokens,
+        justification: justification.reason,
+        reason: 'User override with justification'
+      };
+    }
+
+    return { shouldDelegate: false, reason: 'No specialist found for this task' };
+  }
+
+  /**
+   * Find the best specialist for a task based on domain keywords
+   */
+  _findBestSpecialist(task) {
+    const taskLower = task.toLowerCase();
+
+    // Domain keyword matching
+    const domainMatches = {
+      'n8n': ['n8n', 'workflow', 'automation', 'webhook'],
+      'postgres': ['postgres', 'database', 'sql', 'query', 'schema'],
+      'redis': ['redis', 'cache', 'memory', 'key-value'],
+      'github': ['github', 'git', 'repository', 'pull request', 'commit'],
+      'openai': ['openai', 'gpt', 'embedding', 'completion', 'streaming']
+    };
+
+    for (const [domain, keywords] of Object.entries(domainMatches)) {
+      if (keywords.some(kw => taskLower.includes(kw))) {
+        // Find worker agent for this domain
+        const worker = Object.entries(AGENT_HIERARCHY.workers).find(
+          ([name, info]) => info.domain === domain
+        );
+
+        if (worker) {
+          return {
+            agent: worker[0],
+            domain,
+            estimatedTokens: Math.floor(Math.random() * 5000) + 3000, // 3k-8k estimate
+            reason: `Specialist in ${domain}`
+          };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Record successful validation
+   */
+  _recordValidation(agent, task, boss, reviewDetails, nonStandard = false) {
+    const validation = {
+      timestamp: new Date().toISOString(),
+      agent,
+      task,
+      boss,
+      reviewDetails,
+      nonStandard,
+      approved: true
+    };
+
+    this.validations.push(validation);
+
+    console.log(chalk.green('\n✅ HIERARCHY VALIDATION PASSED'));
+    console.log(chalk.dim(`Worker: ${agent}`));
+    console.log(chalk.dim(`Boss Review: ${boss}`));
+    console.log(chalk.dim(`Details: ${reviewDetails}`));
+
+    if (nonStandard) {
+      console.log(chalk.yellow('⚠️  Non-standard boss assignment logged'));
+    }
+
+    return {
+      approved: true,
+      agent,
+      boss,
+      task,
+      reviewDetails,
+      nonStandard,
+      validation
+    };
+  }
+
+  /**
+   * Record hierarchy violation
+   */
+  _recordViolation(agent, task, reason) {
+    const violation = {
+      timestamp: new Date().toISOString(),
+      agent,
+      task,
+      reason,
+      approved: false,
+      override: true
+    };
+
+    this.violations.push(violation);
+
+    console.log(chalk.red('\n🚨 HIERARCHY VIOLATION RECORDED'));
+    console.log(chalk.dim(`Agent: ${agent}`));
+    console.log(chalk.dim(`Task: ${task}`));
+    console.log(chalk.dim(`Reason: ${reason}`));
+    console.log(chalk.yellow('\n⚠️  This violation will be logged for quarterly review'));
+
+    return {
+      approved: true, // Override allowed but logged
+      override: true,
+      agent,
+      task,
+      reason,
+      violation
+    };
+  }
+
+  /**
+   * Get violation report for quarterly review
+   */
+  getViolationReport() {
+    return {
+      totalViolations: this.violations.length,
+      totalValidations: this.validations.length,
+      complianceRate: this.validations.length / (this.violations.length + this.validations.length) * 100,
+      violations: this.violations,
+      validations: this.validations,
+      mostViolatedAgents: this._getMostViolatedAgents()
+    };
+  }
+
+  _getMostViolatedAgents() {
+    const agentCounts = {};
+
+    this.violations.forEach(v => {
+      agentCounts[v.agent] = (agentCounts[v.agent] || 0) + 1;
+    });
+
+    return Object.entries(agentCounts)
+      .sort((a, b) => b[1] - a[1])
+      .map(([agent, count]) => ({ agent, violations: count }));
+  }
+}
+
+// Singleton instance
+const validator = new HierarchyValidator();
+
+export default validator;
+
+/**
+ * USAGE EXAMPLES:
+ *
+ * 1. Validate worker result before acceptance:
+ *
+ *    const result = await workerAgent.execute(task);
+ *    const validation = await hierarchyValidator.validateChain({
+ *      agent: 'n8n-workflow-architect',
+ *      task: 'Create webhook processor',
+ *      output: result.code,
+ *      tokensUsed: result.tokens
+ *    });
+ *
+ *    if (validation.approved) {
+ *      // Proceed with meta-boss review
+ *    } else if (validation.action === 'delegate_to_boss') {
+ *      // Send to domain boss for review
+ *    }
+ *
+ * 2. Pre-task delegation check:
+ *
+ *    const delegation = await hierarchyValidator.checkDelegation(
+ *      'Write comprehensive documentation',
+ *      57000,
+ *      'Boss Claude'
+ *    );
+ *
+ *    if (delegation.shouldDelegate) {
+ *      // Delegate to specialist
+ *    }
+ *
+ * 3. Quick check during execution:
+ *
+ *    const check = await hierarchyValidator.quickCheck('postgres-n8n-specialist');
+ *    if (!check.valid) {
+ *      console.error('Missing boss review:', check.reason);
+ *    }
+ *
+ * 4. Repository boundary check (CANON RULE):
+ *
+ *    const boundaryCheck = await hierarchyValidator.checkRepoBoundary(
+ *      '/Users/user/other-project/file.js',
+ *      '/Users/user/current-project'
+ *    );
+ *
+ *    if (!boundaryCheck.allowed) {
+ *      console.error('Cannot write outside current repo');
+ *      return;
+ *    }
+ *
+ * 5. Quarterly violation report:
+ *
+ *    const report = hierarchyValidator.getViolationReport();
+ *    console.log(`Compliance Rate: ${report.complianceRate.toFixed(1)}%`);
+ *    console.log(`Violations: ${report.totalViolations}`);
+ */

package/lib/index.js

@@ -0,0 +1,15 @@
+/**
+ * Boss Claude Library
+ *
+ * Main entry point for Boss Claude modules
+ */
+
+export * from './identity.js';
+export * from './session.js';
+export * from './memory.js';
+export * from './postgres.js';
+export * from './validators/index.js';
+
+export { default as validators } from './validators/index.js';
+export { default as tokenMonitor } from './token-monitor.js';
+export { default as hierarchyValidator } from './hierarchy-validator.js';