@semanticintent/semantic-chirp-intelligence-mcp 3.0.0

package/build/services/ChirpIntelligence.js

@@ -0,0 +1,213 @@
+/**
+ * 🏒 Chirp Intelligence Service
+ *
+ * Generates contextual hockey chirp commentary based on:
+ * - Semantic chirp contracts (intensity, personality, intent)
+ * - Tool metadata and semantic identity
+ * - Analysis data and context
+ * - Governance enforcement (immutability, validation)
+ */
+import { GOVERNANCE_MONITOR, validateSemanticChirpContract, auditSemanticContract } from '../domain/governance.js';
+import { CHIRP_STYLES } from '../config/chirp-styles.js';
+import { PERSONALITY_MODES } from '../config/personality-modes.js';
+import { TOOL_METADATA } from '../config/tool-metadata.js';
+export class ChirpIntelligence {
+    /**
+     * Generate chirp-enhanced analysis results
+     *
+     * @param toolName - Name of the tool generating the analysis
+     * @param originalData - Raw analysis data to enhance
+     * @param semanticContract - Chirp parameters with semantic intent
+     * @returns Enhanced data with chirp intelligence layer
+     */
+    static enhance(toolName, originalData, semanticContract) {
+        // 🏛️ Governance: Validate semantic contract
+        validateSemanticChirpContract(semanticContract, toolName);
+        // 🏛️ Governance: Freeze contract to prevent violations
+        const frozenContract = Object.freeze({ ...semanticContract });
+        // 🔍 Audit immutability enforcement
+        auditSemanticContract(frozenContract, toolName, "enforcement");
+        // 🛡️ Protected contract with Proxy for runtime enforcement
+        const protectedContract = this.createProtectedContract(frozenContract, toolName);
+        // If chirp disabled, return original data
+        if (protectedContract.enable_chirp === false) {
+            return originalData;
+        }
+        const metadata = TOOL_METADATA[toolName];
+        if (!metadata) {
+            return originalData;
+        }
+        const chirpStyle = CHIRP_STYLES[protectedContract.chirp_intensity || 'standard'];
+        const personality = PERSONALITY_MODES[protectedContract.personality_mode || 'analytical'];
+        return {
+            // Original data preserved
+            ...originalData,
+            // NEW: Chirp Intelligence Layer
+            chirp_intelligence: {
+                // 🎯 Semantic Anchoring (Rule 1): Use observable semantic property
+                tool_identity: metadata.is_ice_engine
+                    ? metadata.tool_semantic_identity
+                    : `${toolName} with chirp intelligence`,
+                style: chirpStyle.tone,
+                personality: personality.voice,
+                intensity: protectedContract.chirp_intensity || 'standard',
+                semantic_context: metadata.hockey_context,
+                // Dynamic chirp based on data
+                analysis_chirp: this.generateContextualChirp(toolName, originalData, chirpStyle, personality),
+                // Intent-driven one-liner
+                intent_summary: this.generateIntentSummary(originalData, personality),
+                // Hockey wisdom
+                ice_cold_truth: this.generateICETruth(originalData, chirpStyle)
+            },
+            // Discovery metadata
+            metadata: {
+                tool_tags: metadata.discovery_tags,
+                intent_category: metadata.intent_category,
+                chirp_energy: chirpStyle.energy,
+                hockey_wisdom_level: "ICE_tier",
+                semantic_depth: "enhanced"
+            }
+        };
+    }
+    /**
+     * Create protected contract with Proxy for immutability enforcement
+     */
+    static createProtectedContract(frozen, toolName) {
+        return new Proxy(frozen, {
+            set() {
+                GOVERNANCE_MONITOR.trackViolation({
+                    rule: "Rule 4 - Immutability Protection",
+                    severity: "error",
+                    tool_name: toolName,
+                    violation_type: "attempted_mutation",
+                    details: "Attempted to set property on immutable ChirpParameters"
+                });
+                throw new Error('🚨 Semantic contract violation: ChirpParameters are immutable after creation');
+            },
+            deleteProperty() {
+                GOVERNANCE_MONITOR.trackViolation({
+                    rule: "Rule 4 - Immutability Protection",
+                    severity: "error",
+                    tool_name: toolName,
+                    violation_type: "attempted_property_deletion",
+                    details: "Attempted to delete property from immutable ChirpParameters"
+                });
+                throw new Error('🚨 Semantic contract violation: Cannot delete ChirpParameters properties');
+            }
+        });
+    }
+    /**
+     * Generate contextual chirp based on tool's chirp potential
+     */
+    static generateContextualChirp(toolName, data, chirpStyle, personality) {
+        const metadata = TOOL_METADATA[toolName];
+        if (!metadata)
+            return "";
+        switch (metadata.chirp_potential) {
+            case "roster_weaknesses":
+                return this.generateRosterChirp(data, chirpStyle, personality);
+            case "schedule_domination":
+                return this.generateScheduleChirp(data, chirpStyle, personality);
+            case "brutal_optimization":
+                return this.generateOptimizationChirp(data, chirpStyle, personality);
+            case "weekly_performance":
+                return this.generateWeeklyPerformanceChirp(data, chirpStyle, personality);
+            case "pickup_strategy":
+                return this.generatePickupStrategyChirp(data, chirpStyle, personality);
+            default:
+                return this.generateGenericChirp(data, chirpStyle, personality);
+        }
+    }
+    static generateRosterChirp(data, chirpStyle, personality) {
+        const injured = data.roster?.filter((p) => p.status && p.status !== "").length || 0;
+        if (injured > 0 && chirpStyle.tone === "brutal_truth") {
+            return `${chirpStyle.prefix} you've got ${injured} injured players mucking up your lineup. That's not championship material! ${chirpStyle.suffix}`;
+        }
+        if (injured > 0 && chirpStyle.tone === "encouraging") {
+            return `${chirpStyle.prefix} moving those ${injured} injured players to IR to optimize your roster. ${chirpStyle.suffix}`;
+        }
+        if (injured > 0 && chirpStyle.tone === "championship_enforcer") {
+            return `${chirpStyle.prefix} ${injured} injured players dragging down your roster. Champions handle their IR like pros. ${chirpStyle.suffix}`;
+        }
+        return `${personality.phrases[0]} your team composition looks solid.`;
+    }
+    static generateScheduleChirp(data, chirpStyle, personality) {
+        const advantage = data.advantage;
+        const diff = Math.abs(data.games_in_hand_difference || 0);
+        if (advantage === "opponent" && chirpStyle.tone === "brutal_truth") {
+            return `${chirpStyle.prefix} your opponent has ${diff} more games than you and you're just sitting there? Time to drop the mittens and get aggressive! ${chirpStyle.suffix}`;
+        }
+        if (advantage === "you" && chirpStyle.tone === "championship_enforcer") {
+            return `${chirpStyle.prefix} You've got ${diff} more games. This is where champions separate from the pretenders. ${chirpStyle.suffix}`;
+        }
+        if (advantage === "you" && chirpStyle.tone === "direct_honest") {
+            return `${chirpStyle.prefix} capitalize on your ${diff}-game advantage ${chirpStyle.suffix}`;
+        }
+        return `${personality.phrases[0]} the schedule advantage situation.`;
+    }
+    static generateOptimizationChirp(data, chirpStyle, personality) {
+        const criticalIssues = data.immediate_issues || 0;
+        const recommendations = data.recommendations?.length || 0;
+        if (criticalIssues > 0 && chirpStyle.tone === "brutal_truth") {
+            return `${chirpStyle.prefix} you've got ${criticalIssues} critical lineup issues and ${recommendations} ways to fix them. Stop window shopping and start dominating! ${chirpStyle.suffix}`;
+        }
+        if (criticalIssues === 0 && chirpStyle.tone === "championship_enforcer") {
+            return `${chirpStyle.prefix} Your lineup is solid but ICE found ${recommendations} ways to push you over the top. ${chirpStyle.suffix}`;
+        }
+        if (recommendations > 5 && chirpStyle.tone === "direct_honest") {
+            return `${chirpStyle.prefix} execute these ${recommendations} optimizations ${chirpStyle.suffix}`;
+        }
+        return `${personality.phrases[0]} ${recommendations} optimization opportunities to consider.`;
+    }
+    static generateWeeklyPerformanceChirp(data, chirpStyle, personality) {
+        const yourGames = data.games_in_hand?.your_remaining || 0;
+        const oppGames = data.games_in_hand?.opponent_remaining || 0;
+        if (yourGames > oppGames && chirpStyle.tone === "championship_enforcer") {
+            return `${chirpStyle.prefix} You've got more games left - time to bury them. ${chirpStyle.suffix}`;
+        }
+        if (yourGames < oppGames && chirpStyle.tone === "brutal_truth") {
+            return `${chirpStyle.prefix} they've got more games - every stat matters now! ${chirpStyle.suffix}`;
+        }
+        return `${personality.phrases[0]} your weekly matchup positioning.`;
+    }
+    static generatePickupStrategyChirp(data, chirpStyle, personality) {
+        const targets = data.streaming_targets?.length || 0;
+        const hotTeam = data.market_intelligence?.top_trending_team || "unknown";
+        if (targets > 10 && chirpStyle.tone === "championship_enforcer") {
+            return `${chirpStyle.prefix} ${targets} targets identified. Focus on ${hotTeam} players for maximum impact. ${chirpStyle.suffix}`;
+        }
+        if (targets > 10 && chirpStyle.tone === "brutal_truth") {
+            return `${chirpStyle.prefix} ${targets} players better than what you've got - are you here to compete or participate? ${chirpStyle.suffix}`;
+        }
+        return `${personality.phrases[0]} ${targets} streaming opportunities on the wire.`;
+    }
+    static generateGenericChirp(data, chirpStyle, personality) {
+        return `${personality.phrases[0]} the data patterns. ${chirpStyle.prefix} taking action based on these insights. ${chirpStyle.suffix}`;
+    }
+    static generateIntentSummary(data, personality) {
+        switch (personality.focus) {
+            case "championship_mindset":
+                return "Championship strategy: Execute these moves for league domination";
+            case "data_driven":
+                return "Statistical analysis: Data-driven recommendations for optimal performance";
+            case "entertainment_value":
+                return "Bottom line: Time to separate the contenders from the pretenders";
+            case "winning_strategy":
+                return "Elite strategy: Next-level moves for next-level results";
+            default:
+                return "Action required: Strategic improvements identified";
+        }
+    }
+    static generateICETruth(data, chirpStyle) {
+        if (chirpStyle.tone === "championship_enforcer") {
+            return "❄️ ICE Cold Truth: Champions make moves, pretenders make excuses.";
+        }
+        if (chirpStyle.tone === "brutal_truth") {
+            return "🔥 Savage Reality: Your competition isn't waiting - neither should you.";
+        }
+        if (chirpStyle.tone === "direct_honest") {
+            return "💪 Real Talk: Smart players act on good intel.";
+        }
+        return "🧠 Smart Play: Optimal decisions lead to optimal results.";
+    }
+}

package/build/services/YahooApiClient.js

@@ -0,0 +1,309 @@
+/**
+ * 🏒 Yahoo Fantasy API Client Service
+ *
+ * Handles all Yahoo Fantasy Sports API interactions including:
+ * - OAuth token management (load, save, refresh)
+ * - Authenticated API requests
+ * - Token expiration handling
+ * - Error handling and retries
+ */
+import fs from 'fs';
+import https from 'https';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export class YahooApiClient {
+    cachedToken = null;
+    tokenFile;
+    apiBase;
+    clientId;
+    clientSecret;
+    constructor(clientId, clientSecret, apiBase = "https://fantasysports.yahooapis.com/fantasy/v2") {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.apiBase = apiBase;
+        this.tokenFile = path.join(__dirname, "..", "..", ".yahoo-oauth.json");
+    }
+    /**
+     * Load OAuth token from file system
+     */
+    loadToken() {
+        try {
+            console.error(`[DEBUG] Looking for token at: ${this.tokenFile}`);
+            if (fs.existsSync(this.tokenFile)) {
+                const tokenData = fs.readFileSync(this.tokenFile, "utf8");
+                const token = JSON.parse(tokenData);
+                console.error(`[DEBUG] Token loaded successfully`);
+                this.cachedToken = token;
+                return token;
+            }
+            else {
+                console.error(`[DEBUG] Token file not found`);
+            }
+        }
+        catch (error) {
+            console.error("[ERROR] Error loading token:", error);
+        }
+        return null;
+    }
+    /**
+     * Save OAuth token to file system
+     */
+    saveToken(token) {
+        token.expires_at = Date.now() + (token.expires_in * 1000);
+        fs.writeFileSync(this.tokenFile, JSON.stringify(token, null, 2));
+        this.cachedToken = token;
+        console.error("[DEBUG] Token saved successfully");
+    }
+    /**
+     * Refresh expired OAuth token
+     */
+    async refreshAccessToken() {
+        const token = this.cachedToken || this.loadToken();
+        if (!token) {
+            throw new Error("No refresh token available. Please re-authenticate.");
+        }
+        console.error("[DEBUG] Refreshing access token...");
+        const tokenData = new URLSearchParams({
+            client_id: this.clientId,
+            client_secret: this.clientSecret,
+            redirect_uri: "oob",
+            refresh_token: token.refresh_token,
+            grant_type: "refresh_token",
+        });
+        const options = {
+            hostname: "api.login.yahoo.com",
+            port: 443,
+            path: "/oauth2/get_token",
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Content-Length": tokenData.toString().length,
+            },
+        };
+        return new Promise((resolve, reject) => {
+            const req = https.request(options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk;
+                });
+                res.on("end", () => {
+                    try {
+                        const newToken = JSON.parse(data);
+                        this.saveToken(newToken);
+                        console.error("[DEBUG] Token refreshed successfully");
+                        resolve(newToken.access_token);
+                    }
+                    catch (error) {
+                        reject(new Error(`Failed to parse token response: ${error}`));
+                    }
+                });
+            });
+            req.on("error", (error) => {
+                reject(error);
+            });
+            req.write(tokenData.toString());
+            req.end();
+        });
+    }
+    /**
+     * Get valid access token, refreshing if necessary
+     */
+    async getValidAccessToken() {
+        const token = this.cachedToken || this.loadToken();
+        if (!token) {
+            throw new Error("No authentication token found! Run: node authenticate.js");
+        }
+        // Check if token is expired (with 5 minute buffer)
+        if (token.expires_at && token.expires_at < Date.now() + 300000) {
+            console.error("[DEBUG] Token expired or expiring soon, refreshing...");
+            return await this.refreshAccessToken();
+        }
+        return token.access_token;
+    }
+    /**
+     * Make authenticated request to Yahoo Fantasy API
+     *
+     * @param endpoint - API endpoint path (e.g., "/team/nhl.l.12345.t.1/roster")
+     * @param format - Response format (default: "json")
+     * @returns Parsed API response
+     */
+    async request(endpoint, format = "json") {
+        const accessToken = await this.getValidAccessToken();
+        const url = `${this.apiBase}${endpoint}${endpoint.includes('?') ? '&' : '?'}format=${format}`;
+        console.error(`[DEBUG] API Request: ${endpoint}`);
+        return new Promise((resolve, reject) => {
+            const urlObj = new URL(url);
+            const options = {
+                hostname: urlObj.hostname,
+                port: 443,
+                path: urlObj.pathname + urlObj.search,
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    Accept: "application/json",
+                },
+            };
+            const req = https.request(options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk;
+                });
+                res.on("end", () => {
+                    if (res.statusCode === 401) {
+                        // Token expired, try to refresh and retry
+                        this.refreshAccessToken()
+                            .then(() => this.request(endpoint, format))
+                            .then(resolve)
+                            .catch(reject);
+                        return;
+                    }
+                    if (res.statusCode !== 200) {
+                        reject(new Error(`API returned status ${res.statusCode}: ${data}`));
+                        return;
+                    }
+                    try {
+                        const parsed = JSON.parse(data);
+                        resolve(parsed);
+                    }
+                    catch (error) {
+                        reject(new Error(`Failed to parse API response: ${error}`));
+                    }
+                });
+            });
+            req.on("error", (error) => {
+                reject(error);
+            });
+            req.end();
+        });
+    }
+    /**
+     * Helper: Strip nhl.l. prefix from league ID if present
+     */
+    stripLeaguePrefix(leagueId) {
+        return leagueId.replace(/^nhl\.l\./, '');
+    }
+    /**
+     * Helper: Strip team number from full team ID (nhl.l.12345.t.6 -> 6)
+     */
+    extractTeamNumber(teamId) {
+        const match = teamId.match(/\.t\.(\d+)$/);
+        return match ? match[1] : teamId.replace(/^.*\.t\./, '');
+    }
+    /**
+     * Convenience method: Get team roster
+     */
+    async getTeamRoster(leagueId, teamId) {
+        const cleanLeagueId = this.stripLeaguePrefix(leagueId);
+        const cleanTeamId = this.extractTeamNumber(teamId);
+        return this.request(`/team/nhl.l.${cleanLeagueId}.t.${cleanTeamId}/roster`);
+    }
+    /**
+     * Convenience method: Get league standings
+     */
+    async getLeagueStandings(leagueId) {
+        const cleanLeagueId = this.stripLeaguePrefix(leagueId);
+        return this.request(`/league/nhl.l.${cleanLeagueId}/standings`);
+    }
+    /**
+     * Convenience method: Get team matchup
+     */
+    async getTeamMatchup(leagueId, teamId, week) {
+        const cleanLeagueId = this.stripLeaguePrefix(leagueId);
+        const cleanTeamId = this.extractTeamNumber(teamId);
+        const weekParam = week ? `;week=${week}` : '';
+        return this.request(`/team/nhl.l.${cleanLeagueId}.t.${cleanTeamId}/matchups${weekParam}`);
+    }
+    /**
+     * Convenience method: Get league scoreboard
+     */
+    async getLeagueScoreboard(leagueId, week) {
+        const cleanLeagueId = this.stripLeaguePrefix(leagueId);
+        const weekParam = week ? `;week=${week}` : '';
+        return this.request(`/league/nhl.l.${cleanLeagueId}/scoreboard${weekParam}`);
+    }
+    /**
+     * Convenience method: Get team stats
+     */
+    async getTeamStats(leagueId, teamId) {
+        const cleanLeagueId = this.stripLeaguePrefix(leagueId);
+        const cleanTeamId = this.extractTeamNumber(teamId);
+        return this.request(`/team/nhl.l.${cleanLeagueId}.t.${cleanTeamId}/stats`);
+    }
+    /**
+     * Convenience method: Get league settings
+     */
+    async getLeagueSettings(leagueId) {
+        return this.request(`/league/nhl.l.${leagueId}/settings`);
+    }
+    /**
+     * Convenience method: Get players (for search, trending, etc.)
+     */
+    async getPlayers(leagueId, queryParams = '') {
+        return this.request(`/league/nhl.l.${leagueId}/players${queryParams}`);
+    }
+    /**
+     * Convenience method: Search players by position
+     */
+    async searchPlayers(position, count = 25, leagueId) {
+        const league = leagueId || process.env.YAHOO_LEAGUE_ID;
+        const cleanLeagueId = this.stripLeaguePrefix(league);
+        let queryParams = `;status=A;count=${count}`;
+        if (position) {
+            queryParams += `;position=${position}`;
+        }
+        const data = await this.request(`/league/nhl.l.${cleanLeagueId}/players${queryParams}`);
+        // Parse player data
+        const playersData = data.fantasy_content.league[1].players;
+        const players = Object.keys(playersData)
+            .filter(key => key !== 'count')
+            .map(key => {
+            const playerData = playersData[key].player[0];
+            const playerId = playerData.find((item) => item.player_id)?.player_id;
+            const name = playerData.find((item) => item.name)?.name?.full;
+            const displayPosition = playerData.find((item) => item.display_position)?.display_position;
+            const team = playerData.find((item) => item.editorial_team_abbr)?.editorial_team_abbr;
+            const percentOwned = playerData.find((item) => item.percent_owned)?.percent_owned?.value || "0";
+            return {
+                player_id: playerId,
+                name: name,
+                position: displayPosition,
+                team: team,
+                percent_owned: parseFloat(percentOwned),
+                selected_position: []
+            };
+        });
+        return { players };
+    }
+    /**
+     * Convenience method: Get trending players
+     */
+    async getTrendingPlayers(trendType = 'add', count = 25, leagueId) {
+        const league = leagueId || process.env.YAHOO_LEAGUE_ID;
+        const cleanLeagueId = this.stripLeaguePrefix(league);
+        const sortParam = trendType === 'add' ? 'AR' : 'OR';
+        const data = await this.request(`/league/nhl.l.${cleanLeagueId}/players;status=A;sort=${sortParam};count=${count}`);
+        const playersData = data.fantasy_content.league[1].players;
+        const players = Object.keys(playersData)
+            .filter(key => key !== 'count')
+            .map(key => {
+            const playerData = playersData[key].player[0];
+            const playerId = playerData.find((item) => item.player_id)?.player_id;
+            const name = playerData.find((item) => item.name)?.name?.full;
+            const displayPosition = playerData.find((item) => item.display_position)?.display_position;
+            const team = playerData.find((item) => item.editorial_team_abbr)?.editorial_team_abbr;
+            const percentOwned = playerData.find((item) => item.percent_owned)?.percent_owned?.value || "0";
+            return {
+                player_id: playerId,
+                name: name,
+                position: displayPosition,
+                team: team,
+                percent_owned: parseFloat(percentOwned),
+                trending: trendType,
+                selected_position: []
+            };
+        });
+        return { players, trend_type: trendType };
+    }
+}

package/build/template/AnalysisTemplate.js

@@ -0,0 +1,167 @@
+/**
+ * 🏛️ Analysis Template Base Class
+ *
+ * Implements the Template Method Pattern with Semantic Anchoring Governance.
+ *
+ * This abstract class defines the skeleton algorithm for all fantasy hockey analyses,
+ * allowing concrete implementations to customize specific steps while preserving
+ * the overall structure and governance enforcement.
+ *
+ * 🎯 Design Pattern: Template Method
+ * - Fixed algorithm structure (executeAnalysis)
+ * - Customizable hook methods (abstract methods)
+ * - Semantic governance integrated at architecture level
+ *
+ * 🏛️ Governance Integration:
+ * - Rule 1 (Semantic Over Structural): Analysis driven by semantic contracts
+ * - Rule 2 (Intent Preservation): Chirp parameters validated and preserved
+ * - Rule 3 (Observable Anchoring): Metadata provides semantic identity
+ * - Rule 4 (Immutability): Results frozen before return
+ */
+import { GOVERNANCE_MONITOR, validateSemanticChirpContract } from '../domain/governance.js';
+import { TOOL_METADATA } from '../config/tool-metadata.js';
+/**
+ * Abstract base class for all fantasy hockey analyses
+ */
+export class AnalysisTemplate {
+    toolName;
+    analysisType;
+    constructor(toolName, analysisType) {
+        this.toolName = toolName;
+        this.analysisType = analysisType;
+    }
+    /**
+     * 🎯 TEMPLATE METHOD: Main algorithm with fixed structure
+     *
+     * This method defines the invariant steps that all analyses must follow:
+     * 1. Validate semantic contract (governance)
+     * 2. Fetch and prepare data
+     * 3. Execute domain-specific analysis
+     * 4. Generate chirp intelligence
+     * 5. Format and freeze results
+     *
+     * Concrete classes CANNOT override this method - they implement the hooks.
+     */
+    async executeAnalysis(args, semanticContract) {
+        const startTime = Date.now();
+        // 🏛️ Governance Step 1: Validate semantic contract
+        this.validateContract(semanticContract);
+        // Track analysis start
+        GOVERNANCE_MONITOR.trackAnalysisStart(this.analysisType);
+        try {
+            // Step 2: Fetch data (hook method)
+            const rawData = await this.fetchData(args);
+            // Step 3: Prepare data for analysis (hook method)
+            const preparedData = await this.prepareData(rawData, args);
+            // Step 4: Execute core analysis logic (hook method)
+            const analysisResults = await this.analyzeData(preparedData, args);
+            // Step 5: Generate chirp intelligence (hook method)
+            const chirpEnhanced = await this.generateChirp(analysisResults, semanticContract, preparedData);
+            // Step 6: Format response (hook method)
+            const response = await this.formatResponse(chirpEnhanced, preparedData);
+            // 🏛️ Governance Step 7: Freeze response (immutability)
+            const frozenResponse = this.freezeResponse(response);
+            // Track analysis completion
+            const duration = Date.now() - startTime;
+            GOVERNANCE_MONITOR.trackAnalysisComplete(this.analysisType, duration);
+            return frozenResponse;
+        }
+        catch (error) {
+            // Track failed analysis
+            const duration = Date.now() - startTime;
+            GOVERNANCE_MONITOR.trackAnalysisComplete(this.analysisType, duration);
+            throw error;
+        }
+    }
+    // ==========================================
+    // 🛡️ GOVERNANCE METHODS (Concrete - Shared)
+    // ==========================================
+    /**
+     * Validate semantic contract and track governance
+     */
+    validateContract(contract) {
+        // 🏛️ Rule 2: Intent Preservation
+        // Note: validateSemanticChirpContract internally calls auditSemanticContract
+        validateSemanticChirpContract(contract, this.toolName);
+    }
+    /**
+     * Freeze response to enforce immutability
+     *
+     * 🏛️ Rule 4: Immutability Protection
+     */
+    freezeResponse(response) {
+        // Deep freeze the response object
+        Object.freeze(response);
+        if (response.analysis_insights) {
+            Object.freeze(response.analysis_insights);
+        }
+        if (response.recommendations) {
+            response.recommendations.forEach((rec) => Object.freeze(rec));
+            Object.freeze(response.recommendations);
+        }
+        if (response.chirp_intelligence) {
+            Object.freeze(response.chirp_intelligence);
+        }
+        if (response.metadata) {
+            Object.freeze(response.metadata);
+        }
+        GOVERNANCE_MONITOR.immutability_enforced++;
+        return response;
+    }
+    /**
+     * Get tool metadata for semantic decisions
+     *
+     * 🏛️ Rule 3: Observable Anchoring
+     */
+    getToolMetadata() {
+        return TOOL_METADATA[this.toolName] || {};
+    }
+    /**
+     * Check if this is an ICE (Intent Chirp Engine) tool
+     *
+     * 🏛️ Rule 1: Semantic Over Structural
+     * Uses observable property instead of string comparison
+     */
+    isIceTool() {
+        const metadata = this.getToolMetadata();
+        return metadata.is_ice_engine === true;
+    }
+    /**
+     * Get semantic defaults for this tool
+     */
+    getSemanticDefaults() {
+        const metadata = this.getToolMetadata();
+        // ICE tools default to ice_cold intensity
+        if (this.isIceTool()) {
+            return {
+                chirp_intensity: "ice_cold",
+                personality_mode: "championship_coach",
+                enable_chirp: true,
+                semantic_intent: "system_default"
+            };
+        }
+        // Standard tools use standard intensity
+        return {
+            chirp_intensity: "standard",
+            personality_mode: "analytical",
+            enable_chirp: true,
+            semantic_intent: "system_default"
+        };
+    }
+    /**
+     * Merge user contract with semantic defaults
+     *
+     * 🏛️ Rule 2: Intent Preservation
+     * User-provided values take precedence over defaults
+     */
+    mergeContractWithDefaults(userContract) {
+        const defaults = this.getSemanticDefaults();
+        return {
+            ...defaults,
+            ...userContract,
+            // If user explicitly set values, preserve semantic intent
+            semantic_intent: userContract.semantic_intent ||
+                (Object.keys(userContract).length > 0 ? "user_requested" : "system_default")
+        };
+    }
+}