@cstack-protocol/pingala 1.0.0

package/src/tools/analyze-stack.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { PingalaEngine } from "../core/pingala.js";
+import { MethodologyLoader } from "../core/methodology.js";
+import { Governor } from "../core/governor.js";
+import { Rule531, type ToolInstance } from "../core/531-rule.js";
+import { EngagementAnalyzer, type ToolWithEngagement } from "../core/engagement-analyzer.js";
+import { DiamondMapper } from "../core/life-area-mapper.js";
+import { ConvexHttpClient } from "convex/browser";
+
+// Hardcoded for now to unblock, but should be env var
+const CONVEX_URL = process.env.CONVEX_URL || "https://impressive-hamster-318.convex.cloud";
+const client = new ConvexHttpClient(CONVEX_URL);
+
+// Minimal Protocol Schema: Only what is needed for 5:3:1 Validation
+const ToolSchema = z.object({
+    name: z.string(),
+    role: z.enum(["Anchor", "Active", "Supporting"]),
+    // Optional enrichment data (passed through, not inferred)
+    category: z.string().optional(),
+    description: z.string().optional(),
+    context: z.string().optional(),  // e.g. "mobile", "work-laptop"
+    functionId: z.string().optional(), // e.g. "browser", "email" - for clustering
+    // Hierarchical Metadata
+    is_parent: z.boolean().optional(),
+    is_substack: z.boolean().optional(),
+    parent_name: z.string().optional()
+});
+
+export const analyzeStackTool = {
+    name: "analyze_stack",
+    description: "Validates a tool stack against the 5:3:1 Clean Architecture Protocol. Requires a structured list of tools with assigned roles.",
+    schema: {
+        tools: z.array(ToolSchema).describe("List of tools to analyze. MINIMUM REQUIREMENT: { name, role } per tool."),
+        context: z.object({
+            user_intent: z.string().optional(),
+            attention_depth: z.number().min(0).max(100).optional(),
+            dependency_exposure: z.number().min(0).max(100).optional()
+        }).optional()
+    },
+    handler: async (args: {
+        tools: any[];
+        context?: {
+            user_intent?: string;
+            attention_depth?: number;
+            dependency_exposure?: number;
+        };
+    }) => {
+        // Direct Mapping: No inference, no aliases. 
+        // We trust the LLM/User to provide the correct structure.
+        const toolList: any[] = args.tools.map(t => ({
+            name: t.name,
+            role: t.role,
+            category: t.category,
+            context: t.context,
+            functionId: t.functionId,
+            is_parent: t.is_parent,
+            is_substack: t.is_substack,
+            parent_name: t.parent_name
+        }));
+
+        // 1. Structural Audit (Stability Norms via API/Convex)
+        let validation;
+        let diffSource = "Local (Fallback)";
+
+        try {
+            // "stacks:validateAndStore" 
+            const apiKey = process.env.CSTACK_API_KEY || "anonymous";
+
+            validation = await client.mutation("stacks:validateAndStore" as any, {
+                operatorHash: apiKey, // Using API Key as identity proxy for now
+                tools: toolList,
+                agentId: "Pingala-MCP-v1"
+            });
+            diffSource = "CSTACK API (Convex)";
+        } catch (e) {
+            console.error("API Validation Failed, falling back to local:", e);
+            validation = Rule531.validate({ tools: toolList });
+        }
+
+        // @ts-ignore - geometry is dynamically added
+        const { geometry } = validation;
+        const strain_signals = validation.violations;
+
+        // 2. Engagement & Fragmentation Analysis
+        const engagement = EngagementAnalyzer.classifyByEngagement(toolList as ToolWithEngagement[]);
+        const fragmentation = EngagementAnalyzer.detectFragmentation(toolList as ToolWithEngagement[]);
+
+        // 3. CSI Computation (Stateless)
+        const diagnosis = await PingalaEngine.diagnose({
+            tools: toolList,
+            scores: {
+                attention_depth: args.context?.attention_depth || 50,
+                dependency_exposure: args.context?.dependency_exposure || 50
+            }
+        });
+
+        // 4. Maturity Assessment
+        const context = Governor.getGovernanceContext();
+        const maturity = {
+            level: context.maturity_level,
+            name: context.maturity_name,
+            guidance: `Validated via ${diffSource}. Monitor your Strain Signals to maintain Crystalline Norms.`
+        };
+
+        // 5. Construct Consolidated Report
+        const report = {
+            type: "governance_report",
+            version: "0.5.0 (Stability Norms)",
+            timestamp: new Date().toISOString(),
+            csi_score: diagnosis.csi_score,
+            functional_geometry: {
+                // @ts-ignore
+                core: geometry.core,
+                // @ts-ignore
+                contexts: geometry.contexts,
+                slots: toolList.reduce((acc: any, tool) => {
+                    const fid = tool.functionId || "Unclassified";
+                    if (!acc[fid]) acc[fid] = { id: fid, primary_role: tool.role, nodes: [] };
+                    acc[fid].nodes.push({
+                        name: tool.name,
+                        role: tool.role,
+                        context: tool.context,
+                        is_parent: tool.is_parent,
+                        is_substack: tool.is_substack,
+                        parent_name: tool.parent_name
+                    });
+                    return acc;
+                }, {})
+            },
+            audit_result: {
+                isValid: validation.isValid && fragmentation.length === 0,
+                strain_signals,
+                recommendations: [
+                    strain_signals.length > 0 ? "Strain detected. Adjust stack to align with Crystalline Norms." : "Structure is coherent.",
+                    fragmentation.length > 0 ? "Consolidate your functional nodes to reduce context switching." : "No fragmentation detected."
+                ]
+            },
+            engagement_reality: {
+                high_engagement_hubs: engagement.high_engagement.map(t => t.name),
+                fragmentation_clusters: fragmentation.map(f => f.functionId)
+            },
+            maturity_assessment: maturity,
+            inner_diamond: new DiamondMapper().mapToDiamond(toolList, false)
+        };
+
+        return {
+            content: [{
+                type: "text" as const,
+                text: JSON.stringify(report, null, 2)
+            }]
+        };
+    }
+};

package/src/tools/audit-workspace.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { PingalaEngine } from "../core/pingala.js";
+import type { ToolInstance } from "../core/531-rule.js";
+
+/**
+ * Tool definition for auditing a workspace.
+ */
+export const auditWorkspaceTool = {
+    name: "audit_workspace",
+    description: "Scans a workspace for .agent configuration and evaluates 5:3:1 protocol alignment (CSI/SAS).",
+    schema: {
+        path: z.string().describe("The absolute path to the workspace directory to audit.")
+    },
+    handler: async (args: { path: string }) => {
+        const workspacePath = args.path;
+        const agentPath = path.join(workspacePath, ".agent");
+
+        const report: any = {
+            workspace: workspacePath,
+            agent_found: fs.existsSync(agentPath),
+            timestamp: new Date().toISOString()
+        };
+
+        if (!report.agent_found) {
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: `Pingala Analysis: Workspace '${workspacePath}' is unmapped. No '.agent' directory found. High risk of cognitive erosion.`
+                }]
+            };
+        }
+
+        // Simplified tool detection for MVP
+        // In a real scenario, this would parse vault.yaml or scan files
+        const mockTools: ToolInstance[] = [
+            { name: "Claude/Antigravity", category: "Intelligence", role: "Anchor" }
+        ];
+
+        const diagnosis = PingalaEngine.diagnose({ tools: mockTools });
+
+        return {
+            content: [{
+                type: "text" as const,
+                text: JSON.stringify({ ...report, diagnosis }, null, 2)
+            }]
+        };
+    }
+};

package/src/tools/calculate-csi.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { Governor } from "../core/governor.js";
+import { PingalaEngine } from "../core/pingala.js";
+
+export const calculateCsiTool = {
+    name: "calculate_csi",
+    description: "Computes current Cognitive Sovereignty Index (0-100) from telemetry scores. Allows recording of Attention Depth and Dependency Exposure.",
+    schema: {
+        attention_depth: z.number().min(0).max(100).optional().describe("0-100 score for attention quality/deep work"),
+        dependency_exposure: z.number().min(0).max(100).optional().describe("0-100 score for workflow independence from AI"),
+        time_window: z.enum(["7d", "30d", "90d"]).optional().describe("Lookback period (default 7d)"),
+        tools: z.array(z.any()).optional().describe("Optional list of tools to calculate CSI for (Stateless Mode)")
+    },
+    handler: async (args: {
+        attention_depth?: number;
+        dependency_exposure?: number;
+        time_window?: string;
+        tools?: any[];
+    }) => {
+        // Record telemetry if provided (only if not in stateless mode or if we specifically want to save)
+        if (args.attention_depth !== undefined || args.dependency_exposure !== undefined) {
+            Governor.recordTelemetry({
+                attention_depth: args.attention_depth,
+                dependency_exposure: args.dependency_exposure
+            });
+        }
+
+        const stack = args.tools || Governor.getStack();
+        const diagnosis = await PingalaEngine.diagnose({ tools: stack });
+
+        return {
+            content: [{
+                type: "text" as const,
+                text: JSON.stringify(diagnosis, null, 2)
+            }]
+        };
+    }
+};

package/src/tools/cs-audit.ts

@@ -0,0 +1,384 @@
+import { z } from "zod";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { PingalaEngine } from "../core/pingala.js";
+import { MethodologyLoader } from "../core/methodology.js";
+import { Governor } from "../core/governor.js";
+import type { ToolInstance } from "../core/531-rule.js";
+import { EngagementAnalyzer, type ToolWithEngagement } from "../core/engagement-analyzer.js";
+import { ConsentManager } from "../core/consent-manager.js";
+import { BaguaMapper, DiamondMapper } from "../core/life-area-mapper.js";
+
+/**
+ * cs_audit Tool: The Governor's Primary Interface
+ * 
+ * Accepts tool lists (raw, from vault, or from image) and runs the
+ * 6-step Intervention Logic to audit stack alignment with 5:3:1.
+ * Supports three levels of depth (L1, L2, L3) gated by consent.
+ */
+
+// Minimal Protocol Schema: Matches analyze_stack
+const ToolSchema = z.object({
+    name: z.string(),
+    role: z.enum(["Anchor", "Active", "Supporting"]),
+    category: z.string().optional(),
+    description: z.string().optional(),
+    context: z.string().optional(),
+    functionId: z.string().optional()
+});
+
+export const csAuditTool = {
+    name: "cs_audit",
+    description: "Audits a stack as a Cognitive Mirror, not just a rule checker. Analyzes ENGAGEMENT REALITY—distinguishing high-engagement hubs from passive utilities—and flags fragmentation (multiple tools per function).",
+    schema: {
+        tools: z.array(ToolSchema).optional().describe("List of tools to audit"),
+        path: z.string().optional().describe("Path to a vault.yaml or .agent directory"),
+        image_uri: z.string().optional().describe("URI to a screenshot of a stack (parsed via LLM vision if available)"),
+        proposed_tool: z.string().optional().describe("A new tool being considered for addition"),
+        current_phase: z.string().optional().describe("Current work phase (e.g., 'pre-launch', 'scale', 'maintenance')"),
+        depth_level: z.enum(["L1", "L2", "L3"]).default("L1").describe("The requested depth level of auditing"),
+        practitioner_mode: z.boolean().optional().describe("If true, overrides consent gates and exposes internal jargon")
+    },
+    handler: async (args: {
+        tools?: Array<any>;
+        path?: string;
+        image_uri?: string;
+        proposed_tool?: string;
+        current_phase?: string;
+        depth_level?: 'L1' | 'L2' | 'L3';
+        practitioner_mode?: boolean;
+    }) => {
+        const depth = args.depth_level || "L1";
+        const practitionerMode = args.practitioner_mode || false;
+
+        // Set workspace context for consent persistence
+        if (args.path) {
+            ConsentManager.setWorkspace(args.path);
+        }
+
+        // CHECK CONSENT
+        if (!ConsentManager.isAuthorized(depth, practitionerMode)) {
+            const prompts = MethodologyLoader.loadConsentPrompts();
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "consent_request",
+                        level: depth,
+                        message: depth === "L2" ? prompts.l2 : prompts.l3,
+                        hint: "Consent will be saved for this workspace."
+                    }, null, 2)
+                }]
+            };
+        }
+        // STEP 0: Input Resolution
+        let toolList: ToolInstance[] = [];
+
+        // Priority: explicit tools > path > image
+        if (args.tools && args.tools.length > 0) {
+            const rawList: ToolInstance[] = args.tools.map(t => ({
+                name: t.name,
+                category: t.category || "Uncategorized",
+                role: (t.role as "Anchor" | "Active" | "Supporting") || "Supporting",
+                avgDailyMinutes: t.avgDailyMinutes,
+                usagePattern: t.usagePattern,
+                functionId: t.functionId,
+                contexts: t.contexts || (t.device ? [t.device] : undefined),
+                isAdapter: t.isAdapter ?? t.contextual_adapter,
+                substack: t.substack ?? t.substacks
+            }));
+            toolList = rawList as ToolWithEngagement[];
+        } else if (args.path) {
+            // Attempt to read from vault
+            const vaultPath = path.join(args.path, "vault.yaml");
+            if (fs.existsSync(vaultPath)) {
+                // For MVP: just indicate vault found, parsing TODO
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify({
+                            type: "clarification",
+                            message: "Vault detected. Please provide tools as a list for now (vault parsing coming soon).",
+                            vault_path: vaultPath
+                        }, null, 2)
+                    }]
+                };
+            } else {
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify({
+                            type: "clarification",
+                            message: `No vault.yaml found at ${args.path}. Please provide tools as a list.`
+                        }, null, 2)
+                    }]
+                };
+            }
+        } else if (args.image_uri) {
+            // Image parsing requires LLM vision - return clarification
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "clarification",
+                        message: "Image received. LLM vision parsing not yet implemented. Please provide tools as a list.",
+                        image_uri: args.image_uri
+                    }, null, 2)
+                }]
+            };
+        } else {
+            // No input provided - ask for stack
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "clarification",
+                        step: 2,
+                        question: "What tools are currently in your stack?",
+                        hint: "List each tool with its name. Optionally include role (Anchor/Active/Supporting) and category."
+                    }, null, 2)
+                }]
+            };
+        }
+
+        // STEP 1: Engagement Analysis (The Cognitive Mirror)
+        const engagement = EngagementAnalyzer.classifyByEngagement(toolList as ToolWithEngagement[]);
+        const fragmentation = EngagementAnalyzer.detectFragmentation(toolList as ToolWithEngagement[]);
+        const anomalies = EngagementAnalyzer.flagAnomalies(toolList as ToolWithEngagement[]);
+        const anchorCheck = EngagementAnalyzer.identifyAnchorEnvironment(toolList as ToolWithEngagement[]);
+
+        // Cognitive Load calculation: High-engagement tools + frag clusters
+        const cognitivelyActiveTools = engagement.high_engagement.length + fragmentation.length;
+
+        if (cognitivelyActiveTools > 9) {
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "intervention",
+                        step: 1,
+                        status: "HARD_STOP",
+                        message: `Your high-engagement stack has ${cognitivelyActiveTools} Active Hubs. The 5:3:1 Protocol limits you to 9. You are in a state of cognitive debt.`,
+                        active_hubs: cognitivelyActiveTools,
+                        max_allowed: 9,
+                        fragmentation_clusters: fragmentation.map(f => f.functionId)
+                    }, null, 2)
+                }]
+            };
+        }
+
+        // STEP 2: Current State Audit
+        const anchors = toolList.filter(t => t.role === "Anchor");
+        const active = toolList.filter(t => t.role === "Active");
+        const supporting = toolList.filter(t => t.role === "Supporting");
+        const unassigned = toolList.filter(t => !t.role);
+
+        // Check for role assignment issues
+        if (unassigned.length > 0) {
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "clarification",
+                        step: 2,
+                        question: "Some tools don't have roles assigned. Please classify these:",
+                        unassigned_tools: unassigned.map(t => t.name),
+                        valid_roles: ["Anchor", "Active", "Supporting"],
+                        rule: "You need exactly 1 Anchor, up to 3 Active, and up to 5 Supporting."
+                    }, null, 2)
+                }]
+            };
+        }
+
+        // Validate structure
+        const structureIssues: string[] = [];
+        if (anchors.length !== 1) {
+            structureIssues.push(`Expected 1 Anchor, found ${anchors.length}.`);
+        }
+        if (active.length > 3) {
+            structureIssues.push(`Expected max 3 Active, found ${active.length}.`);
+        }
+        if (supporting.length > 5) {
+            structureIssues.push(`Expected max 5 Supporting, found ${supporting.length}.`);
+        }
+        if (!anchorCheck.hasAnchor) {
+            structureIssues.push(anchorCheck.observation || "No clear Anchor environment detected.");
+        }
+
+        if (structureIssues.length > 0) {
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "intervention",
+                        step: 2,
+                        status: "STRUCTURE_VIOLATION",
+                        issues: structureIssues,
+                        hint: anchorCheck.hint,
+                        current_structure: {
+                            anchors: anchors.map(t => t.name),
+                            active: active.map(t => t.name),
+                            supporting: supporting.map(t => t.name)
+                        }
+                    }, null, 2)
+                }]
+            };
+        }
+
+        // STEP 3: Fragmentation Intervention
+        if (fragmentation.length > 0) {
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "intervention",
+                        step: 3,
+                        status: "FRAGMENTATION_DETECTED",
+                        message: "You have multiple tools serving the same function. This creates obligation anxiety and check-in loops.",
+                        clusters: fragmentation,
+                        recommendation: "Consolidate to a single tool per function, or explicitly acknowledge the split as intentional."
+                    }, null, 2)
+                }]
+            };
+        }
+
+        // STEP 3-6: Only if proposed_tool is given
+        if (args.proposed_tool) {
+            // Step 3: Value vs Redundancy Test
+            const overlap = toolList.find(t =>
+                t.name.toLowerCase().includes(args.proposed_tool!.toLowerCase()) ||
+                args.proposed_tool!.toLowerCase().includes(t.name.toLowerCase())
+            );
+
+            if (overlap) {
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify({
+                            type: "intervention",
+                            step: 3,
+                            status: "REDUNDANCY_CHECK",
+                            question: `You already have '${overlap.name}'. How is '${args.proposed_tool}' different?`,
+                            existing_tool: overlap.name,
+                            proposed_tool: args.proposed_tool,
+                            hint: "If they serve the same function, this addition violates Stack Substitution rules."
+                        }, null, 2)
+                    }]
+                };
+            }
+
+            // Step 4: Phase Alignment Check
+            if (!args.current_phase) {
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify({
+                            type: "clarification",
+                            step: 4,
+                            question: "What is your current work phase?",
+                            hint: "e.g., 'pre-launch', 'growth', 'scale', 'maintenance'",
+                            context: `You're considering adding '${args.proposed_tool}'. Is it needed for your current phase, or a future one?`
+                        }, null, 2)
+                    }]
+                };
+            }
+
+            // Step 5: Substitution Requirement
+            if (toolList.length >= 9) {
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify({
+                            type: "intervention",
+                            step: 5,
+                            status: "SUBSTITUTION_REQUIRED",
+                            question: `Your stack is at capacity (${toolList.length}/9). If '${args.proposed_tool}' joins, what gets removed?`,
+                            current_stack: toolList.map(t => t.name),
+                            proposed_tool: args.proposed_tool,
+                            rule: "No addition without subtraction."
+                        }, null, 2)
+                    }]
+                };
+            }
+
+            // Step 6: Inner Stack Reflection
+            return {
+                content: [{
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        type: "intervention",
+                        step: 6,
+                        status: "REFLECTION",
+                        question: "Before adding this tool, pause: What internal pattern is driving this consideration?",
+                        prompts: [
+                            "Is this FOMO?",
+                            "Are you in 'expansion-through-addition' mode?",
+                            "What are you avoiding by considering this right now?"
+                        ],
+                        proposed_tool: args.proposed_tool,
+                        current_phase: args.current_phase,
+                        message: "The intervention isn't 'No, don't do that.' It's: Here's your own protocol and how it applies to what you're doing in real-time."
+                    }, null, 2)
+                }]
+            };
+        }
+
+        // Full diagnosis (no proposed tool)
+        const diagnosis = await PingalaEngine.diagnose({
+            tools: toolList
+        });
+        const rules = MethodologyLoader.load531Rules();
+
+        return {
+            content: [{
+                type: "text" as const,
+                text: JSON.stringify({
+                    type: "diagnosis",
+                    version: "0.4.5 (Horizon 1.5)",
+                    protocol_metadata: {
+                        name: "5:3:1 Protocol",
+                        mapping: rules.rawDescription || "1 Anchor, 3 Active, 5 Supporting",
+                        total_limit: rules.maxTools
+                    },
+                    functional_geometry: {
+                        clusters: toolList.reduce((acc: any, tool) => {
+                            const fid = tool.functionId || "Unclassified";
+                            if (!acc[fid]) acc[fid] = { id: fid, primary: tool.name, nodes: [] };
+                            acc[fid].nodes.push({
+                                name: tool.name,
+                                context: tool.context,
+                                is_adapter: tool.isAdapter
+                            });
+                            return acc;
+                        }, {})
+                    },
+                    engagement_reality: {
+                        high_engagement_hubs: engagement.high_engagement.map(t => t.name),
+                        contextual_utilities: engagement.contextual_utility.map(t => t.name),
+                        passive_background: engagement.passive_background.map(t => t.name),
+                        fragmentation_clusters: fragmentation.map(f => f.functionId),
+                        anomalies: anomalies
+                    },
+                    stack_structure: {
+                        anchor: anchors.map(t => t.name),
+                        active: active.map(t => t.name),
+                        supporting: supporting.map(t => t.name)
+                    },
+                    total_tools: toolList.length,
+                    active_hubs: cognitivelyActiveTools,
+                    diagnosis,
+                    life_area_mapping: depth !== "L1" ? new BaguaMapper().mapToolsToAreas(toolList, practitionerMode) : undefined,
+                    inner_diamond: depth === "L3" ? new DiamondMapper().mapToDiamond(toolList, practitionerMode) : undefined,
+                    progression_offer: (depth === "L1" && !ConsentManager.isAuthorized("L2") && Governor.getGovernanceContext().progression.is_l2_eligible) ? {
+                        level: "L2",
+                        message: MethodologyLoader.loadConsentPrompts().l2,
+                        reason: "You have improved your CSI by 10+ points. You've earned a deeper look."
+                    } : undefined,
+                    the_real_question: depth === "L3" ?
+                        "What are you choosing not to see by maintaining this specific friction?" :
+                        "Which 3 apps actually create value in your life, and which are just installed because 'I might need it someday'?"
+                }, null, 2)
+            }]
+        };
+    }
+};