pumuki-ast-hooks 5.3.14 → 5.3.16

package/README.md

@@ -30,15 +30,15 @@
 
 ### Visual Overview
 
-<img src="./docs/images/ast_intelligence_01.png" alt="AST Intelligence System Overview" width="100%" />
+<img src="https://raw.githubusercontent.com/SwiftEnProfundidad/ast-intelligence-hooks/main/docs/images/ast_intelligence_01.png" alt="AST Intelligence System Overview" width="100%" />
 
-<img src="./docs/images/ast_intelligence_02.png" alt="AST Intelligence Workflow" width="100%" />
+<img src="https://raw.githubusercontent.com/SwiftEnProfundidad/ast-intelligence-hooks/main/docs/images/ast_intelligence_02.png" alt="AST Intelligence Workflow" width="100%" />
 
-<img src="./docs/images/ast_intelligence_03.png" alt="AST Intelligence Audit - Part 1" width="100%" />
+<img src="https://raw.githubusercontent.com/SwiftEnProfundidad/ast-intelligence-hooks/main/docs/images/ast_intelligence_03.png" alt="AST Intelligence Audit - Part 1" width="100%" />
 
-<img src="./docs/images/ast_intelligence_04.png" alt="AST Intelligence Audit - Part 2" width="100%" />
+<img src="https://raw.githubusercontent.com/SwiftEnProfundidad/ast-intelligence-hooks/main/docs/images/ast_intelligence_04.png" alt="AST Intelligence Audit - Part 2" width="100%" />
 
-<img src="./docs/images/ast_intelligence_05.png" alt="AST Intelligence Audit - Part 3" width="100%" />
+<img src="https://raw.githubusercontent.com/SwiftEnProfundidad/ast-intelligence-hooks/main/docs/images/ast_intelligence_05.png" alt="AST Intelligence Audit - Part 3" width="100%" />
 
 ---
 
@@ -332,17 +332,57 @@ This library was conceived to solve this fundamental problem by creating a **per
 
 ---
 
-## 🎯 The Result: Never Lose Context Again
+## Complete Architecture and Workflow
 
-With this library, your AI assistant **always knows**:
+The library operates through a multi-phase process that integrates with Git and development workflows to ensure code quality and context persistence. Below is a high-level overview of the architecture and key components:
 
-- ✅ **What you're working on**: Current branch, recent commits, active modules
-- ✅ **What rules apply**: All 798+ platform-specific rules loaded automatically
-- ✅ **What patterns exist**: Architecture patterns detected and documented
-- ✅ **What violations need fixing**: Real-time violation tracking with severity
-- ✅ **How the architecture should be structured**: Clean Architecture, DDD, Feature-First validation
+### Architectural Diagram
 
-**This is not just a validation tool**—it's a **context persistence system** that transforms AI assistants from forgetful helpers into **permanent, context-aware collaborators**.
+```mermaid
+graph LR
+  A[Developer] -->|Runs `ai-start`| B(AI Evidence Initialization)
+  B --> C[.AI_EVIDENCE.json]
+  C --> D[Pre-Tool-Use Validator]
+  D --> E[AI Gate Check]
+  E --> F[Allow/Block Actions]
+  F --> G[Code Editing]
+  G --> H[Pre-Commit Analysis]
+  H --> I[Block Commit if Violations]
+  I --> J[Update Evidence]
+  J --> K[Commit]
+```
+
+### Key Components
+1. **AI Evidence Initialization (`ai-start`)**
+   - Generates `.AI_EVIDENCE.json` with project context and rules.
+   - Answers three critical questions about the task.
+   - Example:
+     ```bash
+     ai-start feature/user-authentication
+     ```
+
+2. **Pre-Tool-Use Validator**
+   - Validates `.AI_EVIDENCE.json` before every AI edit operation.
+   - Ensures context is fresh and rules are loaded.
+
+3. **AI Gate Check**
+   - Checks for blocking violations before allowing actions.
+   - Enforces quality gates.
+
+4. **Pre-Commit Analysis**
+   - Runs AST analysis on staged files.
+   - Blocks commits with critical violations.
+
+5. **Evidence Update**
+   - Updates `.AI_EVIDENCE.json` before commits to maintain context.
+
+### Example Workflow
+1. Developer runs `ai-start` to initialize context.
+2. AI uses context to perform edits.
+3. Pre-commit hook analyzes code and blocks if violations exist.
+4. Developer fixes violations and commits.
+
+For a detailed architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ---
 
@@ -358,7 +398,7 @@ With this library, your AI assistant **always knows**:
   - [Phase 4: Evidence Update Before Commits](#phase-4-evidence-update-before-commits)
 - [Tools & Technologies](#️-tools--technologies)
 - [What, How, and When: The Developer's Perspective](#-what-how-and-when-the-developers-perspective)
-- [The Result: Never Lose Context Again](#-the-result-never-lose-context-again)
+- [Complete Architecture and Workflow](#complete-architecture-and-workflow)
 - [What is it?](#what-is-it)
 - [What problems does it solve?](#what-problems-does-it-solve)
 - [Features](#features)
@@ -394,7 +434,7 @@ With this library, your AI assistant **always knows**:
 #### 🔍 Code Validation
 - ✅ **798+ validation rules** across all platforms with severity-based quality gates
 - ✅ **Multi-platform support**: iOS (Swift/SwiftUI), Android (Kotlin/Jetpack Compose), Backend (TypeScript/NestJS), Frontend (React/Next.js)
-- ✅ **Automatic architecture detection**: Detects multiple patterns per platform (iOS: MVVM, MVVM-C, MVP, VIPER, TCA, Clean Swift, Feature-First + Clean + DDD; Backend: Clean Architecture, DDD, CQRS; Frontend: Feature-First, Component-Based, Atomic Design; Android: MVVM, MVI, MVP, Clean Architecture)
+- ✅ **Automatic architecture detection**: Identifies multiple patterns per platform (iOS: MVVM, MVVM-C, MVP, VIPER, TCA, Clean Swift, Feature-First + Clean + DDD; Backend: Clean Architecture, DDD, CQRS; Frontend: Feature-First, Component-Based, Atomic Design; Android: MVVM, MVI, MVP, Clean Architecture)
 - ✅ **BDD→TDD workflow enforcement**: CRITICAL priority - ensures feature files exist before implementation and tests before code
 - ✅ **Pre-commit Git hooks**: Automatic validation blocks commits with CRITICAL/HIGH violations
 - ✅ **AST analysis engine**: Deep static code analysis using Abstract Syntax Trees
@@ -919,11 +959,6 @@ export HOOK_GUARD_AUTO_REFRESH=true
 export AUTO_COMMIT_ENABLED=true
 export AUTO_PUSH_ENABLED=true
 export AUTO_PR_ENABLED=false
-
-# Analysis mode
-export AUDIT_STRICT=false
-export AUDIT_STAGED_ONLY=false
-export AUDIT_CRITICAL_HIGH_ONLY=false
 ```
 
 ### Configuration Files
@@ -1023,7 +1058,7 @@ Start by fixing CRITICAL and HIGH. MEDIUM and LOW are warnings and don't block c
 ```bash
 # Automatically via MCP
 # Or manually
-./bin/update-evidence.sh --auto --platforms backend,frontend
+bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh
 ```
 
 For more questions, check the issues on GitHub.
@@ -1121,4 +1156,20 @@ Developed by **Pumuki Team®**
 
 ---
 
-**⭐ If this project is useful to you, please consider giving it a star on GitHub.**
+**⭐ If this project is useful to you, please consider giving it a star on GitHub.**
+
+### Run the Audit
+
+To start the interactive audit menu, run:
+
+```bash
+bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh
+```
+
+This will present a menu with options for different audit modes.
+
+For non-interactive use, specify the mode directly:
+
+```bash
+bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh analyze  # Full repository analysis
+bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh staged    # Analyze only staged files (pre-commit mode)

package/docs/RELEASE_NOTES.md

@@ -1,3 +1,39 @@
+# Release Notes - v5.3.15
+
+**Release Date**: December 30, 2025  
+**Type**: Patch Release  
+**Compatibility**: Fully backward compatible with 5.3.x
+
+---
+
+## 🎯 Overview
+
+This release fixes MCP configuration in Windsurf to avoid collisions when multiple projects are open in parallel. It now uses a single global entry with an absolute path to the repo’s local binary and removes the legacy hardcode in the CLI configurator.
+
+---
+
+## 🐛 Bug Fixes
+
+### Fixed: MCP collision when opening multiple repos in Windsurf
+- **Issue**: MCP was generated per workspace with a fixed legacy ID, causing duplicates/cancellations of `ai_gate_check`.
+- **Resolution**: Configuration only in `~/.codeium/windsurf/mcp_config.json` with fixed ID `ast-intelligence-automation` pointing to the local binary; legacy hardcode removed in `pumuki-mcp.js`.
+- **Impact**: MCP no longer collides when working with multiple repos simultaneously.
+
+---
+
+## 📚 Documentation
+- New guide: `docs/MCP_CONFIGURATION.md` explaining global configuration and `ai_gate_check` validation in Windsurf.
+
+---
+
+## 📦 Installation / Upgrade
+```bash
+npm install --save-dev pumuki-ast-hooks@5.3.15
+npm run install-hooks
+```
+
+---
+
 # Release Notes - v5.3.9
 
 **Release Date**: December 29, 2025  

package/docs/RELEASE_NOTES_5.3.4.md

@@ -0,0 +1,170 @@
+# Release Notes - v5.3.4
+
+**Release Date**: December 29, 2025  
+**Type**: Patch Release  
+**Compatibility**: Fully backward compatible with 5.3.x
+
+---
+
+## 🎯 Overview
+
+Version 5.3.4 addresses critical bugs in the audit orchestrator that were preventing correct analysis of repository files. This patch ensures that audit options work as intended and provide accurate violation reports.
+
+---
+
+## 🐛 Bug Fixes
+
+### Fixed: Audit Option 2 Analyzing Only Staged Files
+
+**Issue**: Option 2 (Strict REPO+STAGING) was incorrectly configured with `STAGING_ONLY_MODE=1`, causing it to analyze only staged files instead of the entire repository.
+
+**Impact**: Users running full repository audits were only seeing violations from staged files, missing thousands of potential issues in the codebase.
+
+**Resolution**:
+- Added `unset STAGING_ONLY_MODE` in `full_audit_strict_repo_and_staging()` function
+- Added `export AUDIT_LIBRARY=true` to include library files in analysis
+- Fixed environment variable propagation to Node.js subprocess
+
+**Files Changed**:
+- `scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh`
+
+**Verification**:
+```bash
+# Before: Only staged files analyzed
+npm run audit  # Option 2 → ~376 files, ~546 violations
+
+# After: Full repository analyzed
+npm run audit  # Option 2 → All files, correct violation count
+```
+
+---
+
+### Fixed: AUDIT_LIBRARY Not Passed to Node.js Process
+
+**Issue**: The `AUDIT_LIBRARY` environment variable was set in the shell but not exported to the Node.js subprocess executing `ast-intelligence.js`.
+
+**Impact**: When auditing the library itself, files in `scripts/hooks-system/` were being incorrectly filtered out.
+
+**Resolution**:
+- Modified `run_ast_intelligence()` to explicitly export `AUDIT_LIBRARY` when spawning Node.js process
+- Ensured variable is available in both execution paths (with and without `NODE_PATH`)
+
+**Files Changed**:
+- `scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh` (lines 1014, 1016)
+
+---
+
+### Improved: Staged File Path Matching
+
+**Issue**: Violations in staged files were not being correctly matched due to differences between absolute and relative path formats.
+
+**Impact**: Staged file summary showed incorrect violation counts.
+
+**Resolution**:
+- Enhanced `compute_staged_summary()` to use both relative and absolute paths for matching
+- Implemented more robust path comparison using `endswith()` logic
+- Added `staged-rel.txt` for relative path storage
+
+**Files Changed**:
+- `scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh` (lines 337-370)
+
+---
+
+## 🔧 Improvements
+
+### Enhanced Error Messages
+
+- Improved informative messages when no AST-compatible files are staged (Option 3)
+- Better debug output for troubleshooting audit issues
+
+### Code Quality
+
+- Cleaned up debug console.log statements
+- Improved code organization in audit orchestrator
+
+---
+
+## 📦 Installation
+
+### New Installation
+
+```bash
+npm install --save-dev @pumuki/ast-intelligence-hooks@5.3.4
+npm run install-hooks
+```
+
+### Upgrade from 5.3.3
+
+```bash
+npm install --save-dev @pumuki/ast-intelligence-hooks@5.3.4
+npm run install-hooks  # Recommended to update orchestrator scripts
+```
+
+See [Migration Guide](./MIGRATION_5.3.4.md) for detailed upgrade instructions.
+
+---
+
+## ✅ Verification
+
+After upgrading, verify the fixes:
+
+### Test 1: Full Repository Audit (Option 2)
+
+```bash
+npm run audit
+# Select option 2: "Strict REPO+STAGING"
+```
+
+**Expected**: Should analyze ALL files in repository, not just staged files.
+
+### Test 2: Staging Only Audit (Option 3)
+
+```bash
+git add src/some-file.ts
+npm run audit
+# Select option 3: "Strict STAGING only"
+```
+
+**Expected**: Should analyze only staged files and show correct violations.
+
+---
+
+## 🔄 Breaking Changes
+
+**None**. This is a fully backward-compatible patch release.
+
+---
+
+## 📚 Documentation
+
+- [CHANGELOG](../CHANGELOG.md)
+- [Migration Guide](./MIGRATION_5.3.4.md)
+- [Installation Guide](./INSTALLATION.md)
+- [API Reference](./API_REFERENCE.md)
+
+---
+
+## 🙏 Acknowledgments
+
+Thanks to all users who reported issues and helped identify these bugs.
+
+---
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/discussions)
+- **Email**: freelancemerlos@gmail.com
+
+---
+
+## 🚀 What's Next?
+
+Stay tuned for upcoming features in future releases:
+- Enhanced violation reporting
+- Performance optimizations
+- Additional platform support
+
+---
+
+**Full Changelog**: [5.3.3...5.3.4](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/compare/v5.3.3...v5.3.4)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki-ast-hooks",
-  "version": "5.3.14",
+  "version": "5.3.16",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {
@@ -39,7 +39,9 @@
     "lint": "npm run lint:hooks",
     "lint:hooks": "eslint \"scripts/hooks-system/application/**/*.js\" \"bin/**/*.js\"",
     "build:ts": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "ast:refresh": "node scripts/hooks-system/bin/update-evidence.sh",
+    "ast:audit": "node scripts/hooks-system/infrastructure/ast/ast-intelligence.js"
   },
   "keywords": [
     "ast",

package/scripts/hooks-system/.AI_TOKEN_STATUS.txt

@@ -12,5 +12,5 @@ Source: file
 
 ℹ️  Data is stale. Ensure guards are running and refreshing token usage.
 
-Last updated: 2025-12-29T19:57:52.570Z
+Last updated: 2025-12-30T06:43:17.150Z
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━