@paths.design/caws-cli 10.1.0 → 11.0.0

package/dist/budget-derivation.js

@@ -1,751 +0,0 @@
-/**
- * @fileoverview Budget Derivation Logic
- * Derives budgets from policy.yaml and applies waivers
- * Enhanced with PolicyManager for caching and improved performance
- * @author @darianrosebrook
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-const yaml = require('js-yaml');
-const { defaultPolicyManager } = require('./policy/PolicyManager');
-
-/**
- * Validate policy structure and content
- * @param {Object} policy - Policy object from policy.yaml
- * @throws {Error} If policy is invalid
- */
-function validatePolicy(policy) {
-  // Validate version
-  if (!policy.version) {
-    throw new Error(
-      'Policy missing version field\n' +
-        'Add "version: 1" to .caws/policy.yaml\n' +
-        'Run "caws init" to regenerate policy.yaml'
-    );
-  }
-
-  // Validate risk_tiers exists
-  if (!policy.risk_tiers) {
-    throw new Error(
-      'Policy missing risk_tiers configuration\n' +
-        'Policy must define risk tiers 1, 2, and 3\n' +
-        'Run "caws init" to regenerate policy.yaml'
-    );
-  }
-
-  // Validate each required tier
-  for (const tier of [1, 2, 3]) {
-    if (!policy.risk_tiers[tier]) {
-      throw new Error(
-        `Policy missing configuration for risk tier ${tier}\n` +
-          `Add risk_tiers.${tier} with max_files and max_loc to .caws/policy.yaml\n` +
-          'Run "caws init" to regenerate policy.yaml'
-      );
-    }
-
-    const tierConfig = policy.risk_tiers[tier];
-
-    // Validate max_files
-    if (!tierConfig.max_files || tierConfig.max_files <= 0) {
-      throw new Error(
-        `Invalid max_files for tier ${tier}: ${tierConfig.max_files}\n` +
-          `max_files must be a positive integer\n` +
-          `Fix in .caws/policy.yaml under risk_tiers.${tier}.max_files`
-      );
-    }
-
-    // Validate max_loc
-    if (!tierConfig.max_loc || tierConfig.max_loc <= 0) {
-      throw new Error(
-        `Invalid max_loc for tier ${tier}: ${tierConfig.max_loc}\n` +
-          `max_loc must be a positive integer\n` +
-          `Fix in .caws/policy.yaml under risk_tiers.${tier}.max_loc`
-      );
-    }
-
-    // Validate thresholds if present
-    if (
-      tierConfig.coverage_threshold !== undefined &&
-      (tierConfig.coverage_threshold < 0 || tierConfig.coverage_threshold > 100)
-    ) {
-      throw new Error(
-        `Invalid coverage_threshold for tier ${tier}: ${tierConfig.coverage_threshold}\n` +
-          `coverage_threshold must be between 0 and 100\n` +
-          `Fix in .caws/policy.yaml under risk_tiers.${tier}.coverage_threshold`
-      );
-    }
-
-    if (
-      tierConfig.mutation_threshold !== undefined &&
-      (tierConfig.mutation_threshold < 0 || tierConfig.mutation_threshold > 100)
-    ) {
-      throw new Error(
-        `Invalid mutation_threshold for tier ${tier}: ${tierConfig.mutation_threshold}\n` +
-          `mutation_threshold must be between 0 and 100\n` +
-          `Fix in .caws/policy.yaml under risk_tiers.${tier}.mutation_threshold`
-      );
-    }
-  }
-
-  // Validate waiver_approval if present
-  if (policy.waiver_approval) {
-    if (
-      policy.waiver_approval.required_approvers !== undefined &&
-      policy.waiver_approval.required_approvers < 0
-    ) {
-      throw new Error(
-        `Invalid waiver_approval.required_approvers: ${policy.waiver_approval.required_approvers}\n` +
-          'required_approvers must be a non-negative integer'
-      );
-    }
-
-    if (
-      policy.waiver_approval.max_duration_days !== undefined &&
-      policy.waiver_approval.max_duration_days <= 0
-    ) {
-      throw new Error(
-        `Invalid waiver_approval.max_duration_days: ${policy.waiver_approval.max_duration_days}\n` +
-          'max_duration_days must be a positive integer'
-      );
-    }
-  }
-}
-
-/**
- * Get default policy as fallback
- * @returns {Object} Default CAWS policy
- */
-function getDefaultPolicy() {
-  return {
-    version: 1,
-    risk_tiers: {
-      1: {
-        max_files: 25,
-        max_loc: 1000,
-        coverage_threshold: 90,
-        mutation_threshold: 70,
-        contracts_required: true,
-        manual_review_required: true,
-        description: 'Critical changes requiring manual review',
-      },
-      2: {
-        max_files: 50,
-        max_loc: 2000,
-        coverage_threshold: 80,
-        mutation_threshold: 50,
-        contracts_required: true,
-        manual_review_required: false,
-        description: 'Standard features with automated gates',
-      },
-      3: {
-        max_files: 100,
-        max_loc: 5000,
-        coverage_threshold: 70,
-        mutation_threshold: 30,
-        contracts_required: false,
-        manual_review_required: false,
-        description: 'Low-risk changes with minimal oversight',
-      },
-    },
-    waiver_approval: {
-      required_approvers: 1,
-      max_duration_days: 90,
-      auto_revoke_expired: true,
-    },
-  };
-}
-
-/**
- * Load policy.yaml synchronously for contexts that can't go async.
- * Falls back to the bundled default policy when the file is absent or invalid.
- * NOTE: bypasses PolicyManager's TTL cache by design — callers that need
- * caching should use the async `deriveBudget` path.
- * @param {string} projectRoot - Project root directory
- * @returns {Object} Policy object (validated, with _isDefault flag if fallback used)
- */
-function loadPolicySync(projectRoot) {
-  const policyPath = path.join(projectRoot, '.caws', 'policy.yaml');
-  if (!fs.existsSync(policyPath)) {
-    return { ...getDefaultPolicy(), _isDefault: true };
-  }
-
-  let policyContent;
-  try {
-    policyContent = yaml.load(fs.readFileSync(policyPath, 'utf-8'));
-  } catch (error) {
-    console.warn(`Could not parse policy.yaml (${error.message}); using defaults`);
-    return { ...getDefaultPolicy(), _isDefault: true };
-  }
-
-  if (!policyContent || typeof policyContent !== 'object') {
-    return { ...getDefaultPolicy(), _isDefault: true };
-  }
-
-  try {
-    validatePolicy(policyContent);
-  } catch (error) {
-    // Policy file exists but is structurally invalid — surface as warning and
-    // fall back to defaults so validation can continue. The PolicyManager
-    // async path uses console.warn for the same shape.
-    console.warn(`Policy has structure violations (${error.message}); using defaults`);
-    return { ...getDefaultPolicy(), _isDefault: true };
-  }
-
-  return policyContent;
-}
-
-/**
- * Normalize spec.risk_tier to a canonical lookup key.
- * Accepts numeric tier (2), numeric-string ("2"), or "T2"/"t2" forms.
- * Returns the numeric tier (2) when the input is recognizable, otherwise
- * returns the original value so downstream "missing tier" logic can report it.
- * @param {*} riskTier - spec.risk_tier
- * @returns {number|*} numeric tier or original value
- */
-function normalizeRiskTier(riskTier) {
-  if (typeof riskTier === 'number') {
-    return riskTier;
-  }
-  if (typeof riskTier === 'string') {
-    const match = riskTier.match(/^T?(\d)$/i);
-    if (match) {
-      return parseInt(match[1], 10);
-    }
-  }
-  return riskTier;
-}
-
-/**
- * Look up a tier in policy.risk_tiers, tolerant of numeric vs string keys.
- * policy.yaml serializes tier keys as strings ("1", "2", "3") while specs
- * may use numeric risk_tier. Check both representations.
- * @param {Object} policy - Policy object with risk_tiers map
- * @param {number|string} tier - Normalized tier key
- * @returns {Object|undefined} Tier budget config or undefined if missing
- */
-function lookupTierBudget(policy, tier) {
-  if (!policy || !policy.risk_tiers) {
-    return undefined;
-  }
-  return policy.risk_tiers[tier] ?? policy.risk_tiers[String(tier)];
-}
-
-/**
- * Build a derived-budget result from a spec, policy, and optional project root.
- * Shared by both `deriveBudget` (async) and `deriveBudgetSync`. Pure function
- * over already-loaded policy — no I/O.
- *
- * Baseline resolution order (per CAWSFIX-07 A1/A2):
- *   1. If spec.change_budget has numeric max_files and max_loc, use it.
- *      Legacy specs still in the tree may carry change_budget; CAWSFIX-03
- *      forbade it in the schema but not the runtime, so we honor it when
- *      present.
- *   2. Otherwise, fall back to policy.risk_tiers[spec.risk_tier].
- *
- * Throws a named-tier error (A3) if the tier isn't present in policy and no
- * spec-level change_budget is available.
- *
- * @param {Object} spec - Working spec
- * @param {Object} policy - Loaded policy object
- * @param {string} projectRoot - Project root (for waiver loading)
- * @returns {Object} { baseline, effective, waivers_applied, derived_at }
- */
-function applyBudgetDerivation(spec, policy, projectRoot) {
-  const riskTier = normalizeRiskTier(spec.risk_tier);
-  const tierBudget = lookupTierBudget(policy, riskTier);
-  const specBudget = spec && spec.change_budget;
-  const hasSpecBudget =
-    specBudget &&
-    typeof specBudget.max_files === 'number' &&
-    typeof specBudget.max_loc === 'number';
-
-  let baseline;
-  if (hasSpecBudget) {
-    baseline = {
-      max_files: specBudget.max_files,
-      max_loc: specBudget.max_loc,
-    };
-  } else if (tierBudget) {
-    baseline = {
-      max_files: tierBudget.max_files,
-      max_loc: tierBudget.max_loc,
-    };
-  } else {
-    const available = policy && policy.risk_tiers ? Object.keys(policy.risk_tiers).join(', ') : 'none';
-    throw new Error(
-      `Risk tier ${spec.risk_tier} not defined in policy.yaml\n` +
-        `Policy only defines tiers: ${available}\n` +
-        `Valid tiers are: 1 (critical), 2 (standard), 3 (low-risk)` +
-        (typeof spec.risk_tier === 'string'
-          ? `\nHint: use numeric risk_tier (e.g., 2) instead of "${spec.risk_tier}"`
-          : '')
-    );
-  }
-
-  let effectiveBudget = { ...baseline };
-
-  if (spec.waiver_ids && Array.isArray(spec.waiver_ids)) {
-    for (const waiverId of spec.waiver_ids) {
-      const waiver = loadWaiver(waiverId, projectRoot);
-      if (waiver && waiver.status === 'active' && isWaiverValid(waiver)) {
-        if (!waiver.gates || !waiver.gates.includes('budget_limit')) {
-          console.warn(
-            `\nWaiver ${waiverId} does not cover 'budget_limit' gate\n` +
-              `   Current gates: [${waiver.gates ? waiver.gates.join(', ') : 'none'}]\n` +
-              `   Add 'budget_limit' to gates array to apply to budget violations\n`
-          );
-          continue;
-        }
-
-        if (waiver.delta) {
-          if (waiver.delta.max_files) {
-            effectiveBudget.max_files += waiver.delta.max_files;
-          }
-          if (waiver.delta.max_loc) {
-            effectiveBudget.max_loc += waiver.delta.max_loc;
-          }
-        }
-      }
-    }
-  }
-
-  return {
-    baseline,
-    effective: effectiveBudget,
-    waivers_applied: spec.waiver_ids || [],
-    derived_at: new Date().toISOString(),
-  };
-}
-
-/**
- * Derive budget for a working spec based on policy and waivers
- * Enhanced to use PolicyManager for caching
- * @param {Object} spec - Working spec object
- * @param {string} projectRoot - Project root directory
- * @param {Object} options - Derivation options
- * @param {boolean} options.useCache - Use cached policy (default: true)
- * @returns {Object} Derived budget with baseline and effective limits
- */
-async function deriveBudget(spec, projectRoot = process.cwd(), options = {}) {
-  try {
-    // Load policy using PolicyManager (with caching)
-    const policyResult = await defaultPolicyManager.loadPolicy(projectRoot, {
-      useCache: options.useCache !== false,
-    });
-
-    const policy = policyResult;
-
-    // Check if using default policy
-    if (policy._isDefault) {
-      const expectedPath = path.join(projectRoot, '.caws', 'policy.yaml');
-      const policyExists = fs.existsSync(expectedPath);
-
-      if (policyExists) {
-        console.error(
-          'Policy file exists but not loaded: ' +
-            expectedPath +
-            '\n' +
-            '   Current working directory: ' +
-            process.cwd() +
-            '\n' +
-            '   Project root: ' +
-            projectRoot +
-            '\n' +
-            '   Cache status: ' +
-            (policy._cacheHit ? 'HIT (may be stale)' : 'MISS') +
-            '\n' +
-            '   This may be a path resolution or caching issue\n'
-        );
-      } else {
-        // Policy.yaml is optional - defaults work fine, so don't warn unnecessarily
-        // Only show info message if user explicitly wants to see it
-        if (options.showPolicyInfo !== false) {
-          // Silent by default - policy.yaml is optional
-        }
-      }
-    }
-
-    return applyBudgetDerivation(spec, policy, projectRoot);
-  } catch (error) {
-    throw new Error(`Budget derivation failed: ${error.message}`);
-  }
-}
-
-/**
- * Synchronous version of deriveBudget for callers that cannot go async.
- * Uses `loadPolicySync` (no PolicyManager caching) and otherwise shares
- * the same derivation semantics as the async variant.
- *
- * Added for CAWSFIX-07: the legacy synchronous call site in
- * `validation/spec-validation.js` was passing the un-awaited Promise from
- * `deriveBudget` into `checkBudgetCompliance`, which then read
- * `derivedBudget.effective.max_files` on an undefined `.effective` —
- * producing the "Cannot read properties of undefined (reading 'max_files')"
- * warning on every schema-compliant spec.
- *
- * @param {Object} spec - Working spec object
- * @param {string} projectRoot - Project root directory
- * @returns {Object} Derived budget with baseline and effective limits
- */
-function deriveBudgetSync(spec, projectRoot = process.cwd()) {
-  try {
-    const policy = loadPolicySync(projectRoot);
-    return applyBudgetDerivation(spec, policy, projectRoot);
-  } catch (error) {
-    throw new Error(`Budget derivation failed: ${error.message}`);
-  }
-}
-
-/**
- * Validate waiver document structure
- * @param {Object} waiver - Waiver document to validate
- * @throws {Error} If waiver structure is invalid
- */
-const WAIVER_REQUIRED_FIELDS = [
-  'id',
-  'applies_to',
-  'gates',
-  'delta',
-  'reason_code',
-  'expires_at',
-  'risk_owner',
-  'approvers',
-  'status',
-];
-
-function validateWaiverStructure(waiver) {
-  // Check all required fields present
-  for (const field of WAIVER_REQUIRED_FIELDS) {
-    if (!(field in waiver)) {
-      throw new Error(
-        `Waiver missing required field: ${field}\n` +
-          `Required fields: ${WAIVER_REQUIRED_FIELDS.join(', ')}\n` +
-          `Fix the waiver file at .caws/waivers/${waiver.id || 'unknown'}.yaml`
-      );
-    }
-  }
-
-  // Validate ID format (WV-XXXX)
-  if (!/^WV-\d{4}$/.test(waiver.id)) {
-    throw new Error(
-      `Invalid waiver ID format: ${waiver.id}\n` +
-        'Waiver IDs must follow the format: WV-XXXX (e.g., WV-0001)\n' +
-        'Where XXXX is a 4-digit number\n' +
-        `Fix the id field in .caws/waivers/${waiver.id}.yaml`
-    );
-  }
-
-  // Validate status (proposed is valid per schema but not applied by derivation)
-  const validStatuses = ['proposed', 'active', 'expired', 'revoked'];
-  if (!validStatuses.includes(waiver.status)) {
-    throw new Error(
-      `Invalid waiver status: ${waiver.status}\n` +
-        `Status must be one of: ${validStatuses.join(', ')}\n` +
-        `Fix the status field in .caws/waivers/${waiver.id}.yaml`
-    );
-  }
-
-  // Validate gates is array
-  if (!Array.isArray(waiver.gates) || waiver.gates.length === 0) {
-    throw new Error(
-      `Invalid waiver gates: ${JSON.stringify(waiver.gates)}\n` +
-        'gates must be a non-empty array of gate names\n' +
-        `Example: gates: ["budget_limit", "coverage_threshold"]\n` +
-        `Fix the gates field in .caws/waivers/${waiver.id}.yaml`
-    );
-  }
-
-  // Validate approvers is array of {handle, approved_at?} objects
-  if (!Array.isArray(waiver.approvers) || waiver.approvers.length === 0) {
-    throw new Error(
-      `Invalid waiver approvers: ${JSON.stringify(waiver.approvers)}\n` +
-        'approvers must be a non-empty array of objects with a `handle` field\n' +
-        'Example: approvers: [{ handle: "tech-lead", approved_at: "2025-01-01T00:00:00Z" }]\n' +
-        `Fix the approvers field in .caws/waivers/${waiver.id}.yaml`
-    );
-  }
-  for (const approver of waiver.approvers) {
-    if (typeof approver !== 'object' || approver === null || typeof approver.handle !== 'string') {
-      throw new Error(
-        `Invalid waiver approver entry: ${JSON.stringify(approver)}\n` +
-          'Each approver must be an object with a required `handle` field (string).\n' +
-          'Expected shape: { handle: "github-or-email", approved_at: "ISO-8601" }\n' +
-          `Fix the approvers field in .caws/waivers/${waiver.id}.yaml`
-      );
-    }
-  }
-
-  // Validate expires_at is valid date string
-  const expiryDate = new Date(waiver.expires_at);
-  if (isNaN(expiryDate.getTime())) {
-    throw new Error(
-      `Invalid waiver expiry date: ${waiver.expires_at}\n` +
-        'expires_at must be a valid ISO 8601 date string\n' +
-        'Example: expires_at: "2025-12-31T23:59:59Z"\n' +
-        `Fix the expires_at field in .caws/waivers/${waiver.id}.yaml`
-    );
-  }
-
-  // Validate delta if present
-  if (waiver.delta) {
-    if (waiver.delta.max_files !== undefined && waiver.delta.max_files < 0) {
-      throw new Error(
-        `Invalid waiver delta.max_files: ${waiver.delta.max_files}\n` +
-          'delta.max_files must be a non-negative integer\n' +
-          `Fix the delta field in .caws/waivers/${waiver.id}.yaml`
-      );
-    }
-
-    if (waiver.delta.max_loc !== undefined && waiver.delta.max_loc < 0) {
-      throw new Error(
-        `Invalid waiver delta.max_loc: ${waiver.delta.max_loc}\n` +
-          'delta.max_loc must be a non-negative integer\n' +
-          `Fix the delta field in .caws/waivers/${waiver.id}.yaml`
-      );
-    }
-  }
-}
-
-/**
- * Load a waiver by ID
- * Enhanced with structure validation and detailed error reporting
- * @param {string} waiverId - Waiver ID (e.g., WV-0001)
- * @param {string} projectRoot - Project root directory
- * @returns {Object|null} Waiver object or null if not found
- */
-function loadWaiver(waiverId, projectRoot) {
-  try {
-    // Validate ID format before attempting to load
-    if (!/^WV-\d{4}$/.test(waiverId)) {
-      console.error(
-        `\nInvalid waiver ID format: ${waiverId}\n` +
-          `   Waiver IDs must be exactly 4 digits: WV-0001 through WV-9999\n` +
-          `   Fix waiver_ids in .caws/working-spec.yaml\n`
-      );
-      return null;
-    }
-
-    const waiverPath = path.join(projectRoot, '.caws', 'waivers', `${waiverId}.yaml`);
-    if (!fs.existsSync(waiverPath)) {
-      console.error(
-        `\nWaiver file not found: ${waiverId}\n` +
-          `   Expected location: ${waiverPath}\n` +
-          `   Create waiver with: caws waiver create\n`
-      );
-      return null;
-    }
-
-    const waiver = yaml.load(fs.readFileSync(waiverPath, 'utf8'));
-
-    // Validate waiver structure
-    try {
-      validateWaiverStructure(waiver);
-    } catch (error) {
-      console.error(`\nInvalid waiver ${waiverId}: ${error.message}\n`);
-      return null;
-    }
-
-    return waiver;
-  } catch (error) {
-    console.error(`\nFailed to load waiver ${waiverId}: ${error.message}\n`);
-    return null;
-  }
-}
-
-/**
- * Check if a waiver is currently valid
- * Enhanced with proper expiry and approval validation
- * @param {Object} waiver - Waiver object
- * @param {Object} policy - Policy configuration (optional)
- * @returns {boolean} Whether waiver is valid and active
- */
-function isWaiverValid(waiver, policy = null) {
-  try {
-    // Check status first
-    if (waiver.status !== 'active') {
-      console.warn(`Waiver ${waiver.id} has status: ${waiver.status}`);
-      return false;
-    }
-
-    // Check if expired
-    if (waiver.expires_at) {
-      const expiryDate = new Date(waiver.expires_at);
-      const now = new Date();
-      if (now > expiryDate) {
-        console.warn(`Waiver ${waiver.id} expired on ${waiver.expires_at}`);
-        return false;
-      }
-    }
-
-    // Check required approvals
-    if (!waiver.approvers || waiver.approvers.length === 0) {
-      console.warn(`Waiver ${waiver.id} has no approvers`);
-      return false;
-    }
-
-    // Validate minimum approvers if policy provided
-    if (policy && policy.waiver_approval && policy.waiver_approval.required_approvers) {
-      const minApprovers = policy.waiver_approval.required_approvers;
-      if (waiver.approvers.length < minApprovers) {
-        console.warn(
-          `Waiver ${waiver.id} has ${waiver.approvers.length} approvers, needs ${minApprovers}`
-        );
-        return false;
-      }
-    }
-
-    // Shallow sanity check. Full schema conformance is enforced by
-    // validateWaiverStructure at load time (see loadWaiver).
-    if (!waiver.id || !waiver.gates) {
-      console.warn(`Waiver ${waiver.id || 'unknown'} missing required fields`);
-      return false;
-    }
-
-    return true;
-  } catch (error) {
-    console.warn(`Waiver validation error: ${error.message}`);
-    return false;
-  }
-}
-
-/**
- * Check if current changes exceed derived budget
- * @param {Object} derivedBudget - Budget from deriveBudget()
- * @param {Object} currentStats - Current change statistics
- * @returns {Object} Budget check result
- */
-function checkBudgetCompliance(derivedBudget, currentStats) {
-  const violations = [];
-
-  if (currentStats.files_changed > derivedBudget.effective.max_files) {
-    violations.push({
-      gate: 'budget_limit',
-      type: 'max_files',
-      current: currentStats.files_changed,
-      limit: derivedBudget.effective.max_files,
-      baseline: derivedBudget.baseline.max_files,
-      message: `File count (${currentStats.files_changed}) exceeds budget (${derivedBudget.effective.max_files})`,
-    });
-  }
-
-  if (currentStats.lines_changed > derivedBudget.effective.max_loc) {
-    violations.push({
-      gate: 'budget_limit',
-      type: 'max_loc',
-      current: currentStats.lines_changed,
-      limit: derivedBudget.effective.max_loc,
-      baseline: derivedBudget.baseline.max_loc,
-      message: `Lines of code (${currentStats.lines_changed}) exceed budget (${derivedBudget.effective.max_loc})`,
-    });
-  }
-
-  return {
-    compliant: violations.length === 0,
-    violations,
-    budget: derivedBudget,
-  };
-}
-
-/**
- * Calculate budget utilization percentages
- * @param {Object} budgetCompliance - Budget compliance result
- * @returns {Object} Utilization percentages
- */
-function calculateBudgetUtilization(budgetCompliance) {
-  const filesPercent =
-    budgetCompliance.budget.effective.max_files > 0
-      ? (budgetCompliance.budget.baseline.max_files / budgetCompliance.budget.effective.max_files) *
-        100
-      : 0;
-
-  const locPercent =
-    budgetCompliance.budget.effective.max_loc > 0
-      ? (budgetCompliance.budget.baseline.max_loc / budgetCompliance.budget.effective.max_loc) * 100
-      : 0;
-
-  return {
-    files: Math.round(filesPercent),
-    loc: Math.round(locPercent),
-    overall: Math.round(Math.max(filesPercent, locPercent)),
-  };
-}
-
-/**
- * Check if changes are approaching budget limit
- * @param {Object} budgetCompliance - Budget compliance result
- * @param {number} threshold - Warning threshold (default 80)
- * @returns {boolean} Whether approaching limit
- */
-function isApproachingBudgetLimit(budgetCompliance, threshold = 80) {
-  const utilization = calculateBudgetUtilization(budgetCompliance);
-  return utilization.overall >= threshold;
-}
-
-/**
- * Generate burn-up report for scope visibility
- * Enhanced with utilization metrics and warnings
- * @param {Object} derivedBudget - Budget from deriveBudget()
- * @param {Object} currentStats - Current change statistics
- * @returns {string} Human-readable burn-up report
- */
-function generateBurnupReport(derivedBudget, currentStats) {
-  const report = [
-    'CAWS Budget Burn-up Report',
-    '===============================',
-    '',
-    `Risk Tier: ${currentStats.risk_tier}`,
-    `Baseline: ${derivedBudget.baseline.max_files} files, ${derivedBudget.baseline.max_loc} LOC`,
-    `Current: ${currentStats.files_changed} files, ${currentStats.lines_changed} LOC`,
-  ];
-
-  if (derivedBudget.waivers_applied.length > 0) {
-    report.push('');
-    report.push(`Waivers Applied: ${derivedBudget.waivers_applied.join(', ')}`);
-    report.push(
-      `Effective Budget: ${derivedBudget.effective.max_files} files, ${derivedBudget.effective.max_loc} LOC`
-    );
-  }
-
-  const filePercent = Math.round(
-    (currentStats.files_changed / derivedBudget.effective.max_files) * 100
-  );
-  const locPercent = Math.round(
-    (currentStats.lines_changed / derivedBudget.effective.max_loc) * 100
-  );
-
-  report.push('');
-  report.push(
-    `File Usage: ${filePercent}% (${currentStats.files_changed}/${derivedBudget.effective.max_files})`
-  );
-  report.push(
-    `LOC Usage: ${locPercent}% (${currentStats.lines_changed}/${derivedBudget.effective.max_loc})`
-  );
-
-  // Add warnings at different thresholds
-  const overall = Math.max(filePercent, locPercent);
-  if (overall >= 95) {
-    report.push('', 'CRITICAL: Budget nearly exhausted!');
-  } else if (overall >= 90) {
-    report.push('', 'WARNING: Approaching budget limits');
-  } else if (overall >= 80) {
-    report.push('', 'Notice: 80% of budget used');
-  }
-
-  return report.join('\n');
-}
-
-module.exports = {
-  deriveBudget,
-  deriveBudgetSync,
-  loadWaiver,
-  isWaiverValid,
-  checkBudgetCompliance,
-  generateBurnupReport,
-  calculateBudgetUtilization,
-  isApproachingBudgetLimit,
-  validatePolicy,
-  getDefaultPolicy,
-  validateWaiverStructure,
-  WAIVER_REQUIRED_FIELDS,
-};