pumuki-ast-hooks 5.6.7 → 5.6.8

package/README.md

@@ -1,685 +1,474 @@
-<p align="center">
-  <img src="./assets/logo.png" alt="PUMUKI - AST Intelligence" width="350" />
-</p>
-
-<h1 align="center">@pumuki/ast-intelligence-hooks</h1>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/pumuki-ast-hooks"><img src="https://img.shields.io/npm/v/pumuki-ast-hooks.svg?style=flat-square&label=npm&color=CB3837" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/pumuki-ast-hooks"><img src="https://img.shields.io/npm/dm/pumuki-ast-hooks.svg?style=flat-square&color=CB3837" alt="npm downloads" /></a>
-  <a href="https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT" /></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-20.x-brightgreen.svg?style=flat-square&logo=node.js" alt="Node.js Version" /></a>
-  <a href="https://www.npmjs.com/"><img src="https://img.shields.io/badge/npm-10%2B-red.svg?style=flat-square&logo=npm" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Backend%20%7C%20Frontend-blue.svg?style=flat-square" alt="Platforms" />
-  <a href="https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/releases"><img src="https://img.shields.io/github/release-date/SwiftEnProfundidad/ast-intelligence-hooks.svg?style=flat-square&label=last%20release" alt="Last Release" /></a>
-  <a href="https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues"><img src="https://img.shields.io/github/issues/SwiftEnProfundidad/ast-intelligence-hooks.svg?style=flat-square" alt="GitHub Issues" /></a>
-</p>
-
-<p align="center">
-  <strong>Enterprise-grade AST Intelligence System for multi-platform code quality enforcement</strong>
-</p>
-
-### Navigation
-
-| Section | Description |
-|---------|-------------|
-| [Quick Start](#quick-start) | Get started in 30 seconds |
-| [Features](#features) | Main capabilities |
-| [Installation](./docs/INSTALLATION.md) | Full installation guide |
-| [Architecture](./docs/ARCHITECTURE.md) | System design & contracts |
-| [API Reference](./docs/API_REFERENCE.md) | Programmatic interface |
-| [Roadmap](./docs/TODO.md) | Planned improvements |
-| [Changelog](./CHANGELOG.md) | Version history |
-| [Contributing](./docs/CONTRIBUTING.md) | How to contribute |
-
 # Pumuki AST Intelligence Framework
 
-## Enterprise AI Context Governance & Code Quality Enforcement
-
-Pumuki AST Intelligence Framework is a **portable, enterprise-grade framework** designed to **govern AI-assisted software development** in large, long-lived, multi-platform projects.
-
-It provides a **deterministic control layer** over AI behavior by combining:
-
-* AST-based static analysis
-* Persistent AI context evidence
-* Rule-based validation
-* Hard AI gating (block / allow)
-* Native Git workflow integration
-
-The framework is **project-agnostic** by design and can be adopted by any organization seeking to use AI **safely, predictably, and at scale**.
-
----
-
-## Problem Statement
-
-AI assistants are powerful but fundamentally unreliable when used in real-world, enterprise codebases:
+ <p align="center">
+   <img src="./assets/logo.png" alt="Pumuki AST Intelligence Framework" width="800" />
+ </p>
 
-* Context degrades across sessions, chats, and tools
-* Architectural rules are suggested but not enforced
-* AI hallucinations introduce subtle, high-impact defects
-* There is no persistent or auditable source of truth
-* Long-running features suffer from context drift
+Portable, project‑agnostic, multi‑platform enterprise framework to govern AI‑assisted development through AST analysis, deterministic evidence, AI Gate controls, and operational automation.
 
-Pumuki addresses these issues by **removing trust from the AI** and replacing it with **evidence, validation, and enforcement**.
+![npm](https://img.shields.io/npm/v/pumuki-ast-hooks.svg)
+![node](https://img.shields.io/badge/node-%3E%3D18-43853d)
+![platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Backend%20%7C%20Frontend-blue)
+![license](https://img.shields.io/badge/license-MIT-black)
 
 ---
 
-## Quick Start
+## Quick Start (30–60s)
 
-1. Instala dependencias: `npm install`
-2. Usa los ganchos: `npx ast-hooks` (menú interactivo)
-3. Modo CI/CD: `bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh`
-4. Consulta la guía: [docs/INSTALLATION.md](./docs/INSTALLATION.md)
+```bash
+npm install --save-dev @pumuki/ast-intelligence-hooks
+npm run install-hooks
+npx ast-hooks
+```
 
 ---
 
-## Installation & Hooks CLI
-
-* Install (dev): `npm install --save-dev @pumuki/ast-intelligence-hooks`
-* Update to latest: `npm install --save-dev @pumuki/ast-intelligence-hooks@latest && npm run install-hooks`
-* Uninstall: `npm uninstall @pumuki/ast-intelligence-hooks`
-* Install/reinstall hooks: `npm run install-hooks` (alias `npx ast-install`)
-* Interactive menu (hook-system): `npx ast-hooks`
-* Evidence guard daemon: `npm run ast:guard:start|stop|restart|status|logs`
-* Refresh evidence: `npm run ast:refresh`
-* Check installed vs latest version: `npm run ast:check-version`
-
----
+## Operational visuals (examples)
 
-## Features
+### Pre‑write enforcement (block before writing)
 
-### Core
+![Pre-write hook output](./assets/Hook_02.png)
 
-* **AST Intelligence** multi-platform (iOS, Android, Backend, Frontend)
-* **Evidence file** `.AI_EVIDENCE.json` as single source of truth
-* **AI Gate** (block/allow) with metrics and enforcement
+### AI Gate (blocked example)
 
-### NEW: Pre-Write Enforcement
+![AI Gate blocked example](./assets/ai_gate.png)
 
-* **Pre-Flight Validation**: Analyze code BEFORE writing to files
-* **In-Memory AST Analysis**: `analyzeCodeInMemory()` for proposed code validation
-* **IDE Hooks**: Real-time blocking in Windsurf, Claude Code, OpenCode
+### ai-start (bootstrap + evidence refresh)
 
-<img src="./assets/Hook_02.png" alt="Windsurf pre-write hook output" width="100%" />
+![ai-start output](./assets/ai-start.png)
 
-<img src="./assets/Hook_01.png" alt="Windsurf post-write hook output" width="100%" />
-### NEW: MCP Integration
+### Pre-flight check (in-memory validation)
 
-* **MCP Server**: Full Model Context Protocol integration
-* **ai_gate_check**: Mandatory gate before AI operations
-* **pre_flight_check**: Validate proposed code before writing
-* **set_human_intent**: Track user goals across sessions
+![pre-flight-check output](./assets/pre-flight-check.png)
 
-![MCP ai_gate_check BLOCKED example](docs/images/ai_gate.png)
+### Interactive menu (orchestrator overview)
 
-### NEW: Cognitive Layers
+The framework includes an interactive audit menu that drives the orchestrator (full audit, strict modes, pattern checks, ESLint suites, AST intelligence, export, etc.).
 
-* **Human Intent**: Persistent user goal tracking with confidence levels
-* **Semantic Snapshot**: Project state awareness for AI context
+```bash
+npx ast-hooks
+```
 
-### Automation
+Documentation:
 
-* **Git-native**: pre-commit / pre-push / CI integration
-* **Git Flow**: `ast:gitflow` for features, `ast:release` for releases
-* **macOS Notifications**: Real-time alerts and guardrails
+- `docs/USAGE.md` (Interactive Menu, non‑interactive `AUDIT_OPTION`, and typical flows)
+- `CHANGELOG.md` (Release notes and changes)
 
 ---
 
 ## Visual Overview
 
-![AST Intelligence System Overview](docs/images/ast_intelligence_01.svg)
+![AST Intelligence System Overview](./assets/ast_intelligence_01.svg)
 
-![AST Intelligence Workflow](docs/images/ast_intelligence_02.svg)
+![AST Intelligence Workflow](./assets/ast_intelligence_02.svg)
 
-![AST Intelligence Audit - Part 1](docs/images/ast_intelligence_03.svg)
+![AST Intelligence Audit - Part 1](./assets/ast_intelligence_03.svg)
 
-![AST Intelligence Audit - Part 2](docs/images/ast_intelligence_04.svg)
+![AST Intelligence Audit - Part 2](./assets/ast_intelligence_04.svg)
 
-![AST Intelligence Audit - Part 3](docs/images/ast_intelligence_05.svg)
+![AST Intelligence Audit - Part 3](./assets/ast_intelligence_05.svg)
 
 ---
 
-## Design Philosophy
-
-Pumuki is built on a few non-negotiable principles:
-
-* **Evidence over conversation**
-  AI does not rely on chat memory. All decisions depend on a persistent evidence file.
+## 1. Identity
 
-* **Gated intelligence**
-  AI actions are explicitly allowed or blocked based on project state.
+### Name
 
-* **AST, not heuristics**
-  Code is analyzed structurally, not via regex or conventions.
+Pumuki AST Intelligence Framework
 
-* **Fail fast, block early**
-  Unsafe or invalid AI actions are prevented before code changes occur.
+### Enterprise positioning (one line)
 
-* **Platform-agnostic governance**
-  The same rules apply consistently across iOS, Android, backend, and frontend.
+Enterprise governance for AI‑assisted development: persistent evidence, deterministic gate, and multi‑platform AST enforcement.
 
 ---
 
-## Core Capabilities
+## 2. Clear definition
 
-### 1. AI Evidence System
+### 2.1 What the framework is
 
-Pumuki introduces a mandatory, versioned **AI Evidence File** (`.AI_EVIDENCE.json`) that acts as the **single source of truth** for AI-assisted development.
+Pumuki AST Intelligence Framework is a portable, project‑agnostic framework for long‑lived systems that governs AI‑assisted work by combining:
 
-It stores:
+- multi‑platform AST analysis;
+- persistent evidence as the source of truth;
+- a deterministic gate (ALLOW/BLOCK);
+- enforcement before writing, before commit, and in CI/CD;
+- MCP integration for agents;
+- Git Flow automation;
+- a guard/daemon and operational signals.
 
-* Active platforms and scopes
-* Architectural and quality rules
-* Detected violations and severities
-* Session and workflow metadata
-* AI gate state
+### 2.2 What problem it solves
 
-The AI **cannot operate** without valid and fresh evidence.
+AI assistants are probabilistic systems: they can produce a coherent change once and a degrading change on the next run, even with the same prompt. In enterprise repositories this causes:
 
----
-
-### 2. AI Gate (Control Primitive)
+- architecture drift;
+- silent introduction of anti‑patterns;
+- security degradation;
+- accumulation of technical debt;
+- loss of traceability.
 
-The AI Gate is the core control mechanism of the framework.
+Pumuki introduces control and operational reproducibility: it does not rely on “conversation”, it relies on evidence and enforcement.
 
-Before any AI-assisted operation:
+### 2.3 Why it exists
 
-* Evidence freshness is validated
+Without governance, AI:
 
-* Violations are evaluated
+- does not preserve verifiable context;
+- does not apply rules deterministically;
+- can break architectural invariants;
+- can introduce high‑impact defects that are not obvious in a superficial review.
 
-* A deterministic decision is made:
+Pumuki exists to make AI usage compatible with enterprise engineering standards.
 
-* **ALLOWED** → operation may proceed
+### 2.4 Why AI cannot be trusted without governance
 
-* **BLOCKED** → operation is rejected with actionable feedback
+Operational reliability is not achieved with prompts. It is achieved with:
 
-This transforms AI from an advisory tool into a **controlled execution actor**.
+- persistent, auditable evidence;
+- formal rules per platform;
+- deterministic enforcement;
+- early blocking of critical violations.
 
 ---
 
-### 3. AST Intelligence Engine
+## 3. Core principles
 
-The AST Intelligence Engine performs deep, language-aware analysis across platforms.
+### 3.1 Evidence over conversation
 
-Capabilities include:
+Decisions are made based on a persistent evidence file (`.AI_EVIDENCE.json`), not chat memory.
 
-* Architectural rule enforcement
-* Security and data safety validation
-* Performance anti-pattern detection
-* Detection of forbidden constructs and flows
+### 3.2 Gated intelligence
 
-The engine operates on **real ASTs**, not text approximations.
+Before any AI‑assisted operation, repository state and evidence are validated. If it does not comply, the operation is blocked.
 
----
+### 3.3 AST, not heuristics
 
-### 4. Git-Native Enforcement
+Rules run on real ASTs and code structure, avoiding fragile approximations.
 
-Pumuki integrates directly with Git workflows:
+### 3.4 Fail fast, block early
 
-* Pre-commit hooks
-* Pre-push hooks
-* Branch and flow validation
+Pumuki blocks as early as possible: pre‑write, pre‑commit, and CI.
 
-Violations can:
+### 3.5 Platform‑agnostic governance
 
-* Block commits
-* Block pushes
-* Prevent unsafe changes from reaching CI/CD
+A single enforcement model governs iOS, Android, backend, and frontend.
 
-Governance happens **before** code reaches production.
+### 3.6 Token economy (cost-aware operation)
 
----
+This framework treats token usage as an operational cost.
 
-### 5. Pre-Flight Validation (NEW)
+- **Batch checks and avoid redundant scans**.
+- **Reuse cached context** when safe.
+- **Ask the user for missing info** instead of exploring blindly.
+- **Keep responses concise**.
 
-The Pre-Flight Validation system analyzes code **BEFORE** it is written to disk:
+This principle is part of the framework contract and is surfaced to agents via:
 
-```javascript
-const { analyzeCodeInMemory } = require('./ast-core');
+- `ai_gate_check` → `mandatory_rules.framework_rules`
+- `pre_flight_check` → `framework_rules`
 
-// Analyze proposed code without writing to file
-const result = analyzeCodeInMemory(proposedCode, virtualFilePath);
+---
 
-if (result.hasCritical) {
-    // BLOCK the write - violations detected
-    console.log('❌ BLOCKED:', result.violations);
-} else {
-    // ALLOW the write
-    console.log('✅ ALLOWED');
-}
-```
+## 4. Architecture and mental model
 
-**Key capabilities:**
+### 4.1 AI Evidence File (`.AI_EVIDENCE.json`)
 
-* Analyze code strings without file I/O
-* Detect critical violations before code is written
-* Platform-aware analysis (iOS, Android, Backend, Frontend)
-* Integration with IDE hooks for real-time blocking
-![Pre-flight check example](docs/images/pre-flight-check.png)
+`.AI_EVIDENCE.json` is the persistent source of truth. It represents the governance state and enables reproducible decisions.
 
----
+It includes:
 
-### 6. MCP Server Integration (NEW)
+- session and branch context;
+- violations by severity;
+- gate state;
+- detected platforms;
+- operational watchers;
+- cognitive layers.
 
-Pumuki exposes a full **Model Context Protocol (MCP)** server for AI agent integration:
+### 4.2 AI Gate (ALLOW / BLOCK)
 
-| Tool | Purpose | Blocking |
-|------|---------|----------|
-| `ai_gate_check` | Mandatory gate before any AI operation | ✅ Yes |
-| `pre_flight_check` | Validate proposed code before writing | ✅ Yes |
-| `read_platform_rules` | Load platform-specific rules | No |
-| `set_human_intent` | Track user goals across sessions | No |
-| `get_human_intent` | Retrieve current user intent | No |
-| `auto_complete_gitflow` | Automate Git Flow cycle | No |
+The AI Gate decides:
 
-**Usage:**
+- **ALLOWED**: proceed (following rules).
+- **BLOCKED**: the operation is blocked with actionable feedback.
 
-```bash
-# Start MCP server
-node scripts/hooks-system/infrastructure/mcp/ast-intelligence-automation.js
-```
+### 4.3 Deterministic enforcement
 
----
+Enforcement happens in layers:
 
-### 7. Cognitive Layers (NEW)
+1) pre‑write in IDEs that support it;
+2) Git hooks as a universal fallback;
+3) MCP gate/pre‑flight for agents;
+4) CI/CD as final enforcement.
 
-Pumuki introduces **Cognitive Layers** to maintain AI context across sessions:
+### 4.4 Cognitive layers
 
-**Human Intent:**
+#### Human Intent (Intentional Memory)
 
-```json
-{
-  "human_intent": {
-    "primary_goal": "Implement user authentication with OAuth2",
-    "secondary_goals": ["Add unit tests", "Update documentation"],
-    "constraints": ["Must use existing User model", "No breaking changes"],
-    "non_goals": ["UI redesign"],
-    "confidence_level": "high",
-    "expires_at": "2026-01-10T12:00:00Z"
-  }
-}
-```
+Defines the human goal, constraints, and expiration.
 
-**Semantic Snapshot:**
+#### Semantic Snapshot (Semantic Memory)
 
-* Current project state awareness
-* Active platforms and detected patterns
-* Architectural context for AI decisions
+Summarizes project state (health, active platforms, gate state) to prevent drift.
 
 ---
 
-## Supported Platforms
+## 5. Features (complete)
 
-Pumuki is multi-platform by default:
+### 5.1 AST Intelligence (iOS, Android, Backend, Frontend)
 
-* iOS (Swift)
-* Android (Kotlin)
-* Backend (Node.js / NestJS)
-* Frontend (React / Next.js)
+Multi‑platform AST‑based analysis:
 
-The framework is extensible to additional platforms and languages.
+- iOS (Swift)
+- Android (Kotlin)
+- Backend (Node.js / NestJS)
+- Frontend (React / Next.js)
 
----
+### 5.2 Pre‑write enforcement
 
-## AI IDE Compatibility (Pre-Write Enforcement)
+Block before writing when the IDE can intercept operations.
 
-Pumuki supports **real-time code blocking** in IDEs with pre-write hooks:
+### 5.3 In‑memory AST analysis
 
-| IDE | Hook Support | Blocks Before Write? | Fallback |
-|-----|--------------|---------------------|----------|
-| **Windsurf** | `pre_write_code` | ✅ YES | Git pre-commit |
-| **Claude Code** | `PreToolUse` (Write/Edit) | ✅ YES | Git pre-commit |
-| **OpenCode** | Plugin `tool.execute.before` | ✅ YES | Git pre-commit |
-| **Codex CLI** | Approval policies only | ⚠️ Manual | Git pre-commit |
-| **Cursor** | `afterFileEdit` only | ⚠️ Post-write | Git pre-commit |
-| **Kilo Code** | Not documented | ⚠️ No | Git pre-commit |
-
-### How It Works
-
-```text
-AI generates code → IDE Hook intercepts → AST Intelligence analyzes → 
-  ├─ Critical violations? → ❌ BLOCKED (code not written)
-  └─ No violations? → ✅ ALLOWED (code written)
-```
-
-### Enforcement Layers
+Validation over proposed code as a string (without writing to disk).
 
-1. **IDE Hooks** (Windsurf, Claude Code, OpenCode): Block BEFORE code is written
-2. **Git Pre-Commit**: Block commits with violations (100% fallback for all IDEs)
-3. **MCP Gate**: AI cannot proceed without passing `ai_gate_check`
+### 5.4 IDE hooks
 
-> **Note**: For IDEs without pre-write hooks, the Git pre-commit hook provides 100% enforcement at commit time.
+IDE integrations to intercept changes before writing (or fallback via Git).
 
-### PreToolUse Guard (`hooks/pre-tool-use-guard.ts`)
+### 5.5 MCP server
 
-This repository includes a **PreToolUse guard hook** that runs *before* `Edit` / `Write` / `MultiEdit` operations (where supported by the IDE integration).
+MCP server for agents with blocking and non‑blocking tools.
 
-When it runs:
+### 5.6 Git hooks
 
-* In IDEs that support **PreToolUse** interception (e.g. Claude Code integrations)
-* Before code is written to disk
+Universal Git‑level enforcement (pre‑commit / pre‑push) to prevent violations from entering history.
 
-What it does:
+### 5.7 Git Flow automation
 
-* Analyzes the **proposed code** using `analyzeCodeInMemory()`.
-* If the IDE only provides **partial diffs** (`tool_input.edits`), the hook reconstructs the final candidate file content by applying `old_string → new_string` edits over the current file content, then analyzes the result.
-* **Blocks** the operation when **CRITICAL/HIGH** violations are detected (exit code `2`).
+Automation of feature/fix cycles and releases.
 
-Why it exists:
+### 5.8 macOS notifications
 
-* To ensure **enforcement happens before write**, not only at commit time.
-* To prevent silent injection of high-impact patterns (e.g. empty `catch {}`) during AI-assisted edits.
+Operational notifications for gate, evidence, health, guard, and tokens.
 
-See [`scripts/hooks-system/infrastructure/cascade-hooks/README.md`](./scripts/hooks-system/infrastructure/cascade-hooks/README.md) for installation instructions.
+### 5.9 Evidence guard daemon
 
----
+Guard/daemon to keep evidence fresh and reduce drift during long sessions.
 
-## Typical Enterprise Use Cases
+### 5.10 CI/CD enforcement
 
-* Long-running feature development with AI assistance
-* Multi-day or multi-chat workflows
-* Large monorepos and distributed teams
-* Strict Clean Architecture enforcement
-* Regulated or compliance-sensitive environments
+Apply the same rules in pipelines.
 
 ---
 
-## Installation
+## 6. Pre‑Write Enforcement
 
-**Requirements**
+### 6.1 What it does
 
-* Node.js 20 (see `.nvmrc`)
-* npm 10+
+Analyzes code before writing it to disk. This prevents dangerous or degrading patterns from even entering the working tree.
 
-Install as a development dependency:
+### 6.2 IDE interception
 
-```bash
-npm install --save-dev @pumuki/ast-intelligence-hooks
-```
+When the IDE supports pre‑write hooks, the framework intercepts edit/write operations and validates the final content.
 
-Legacy (deprecated):
-
-```bash
-npm install --save-dev pumuki-ast-hooks
-```
+### 6.3 Content reconstruction from partial diffs
 
-Initialize AI evidence:
+If the IDE provides partial diffs, the system reconstructs the final content by applying `old_string → new_string` transformations over the current state before analyzing.
 
-```bash
-npx ai-start
-```
+### 6.4 Blocking behavior
 
-### What is `ai-start` and when should you run it?
+If CRITICAL/HIGH violations exist, the operation is blocked.
 
-`ai-start` refreshes the project AI context and updates `.AI_EVIDENCE.json` so the system has a **fresh, auditable source of truth** before any AI-assisted work.
+### 6.5 Example (in‑memory pre‑flight)
 
-Run it when:
+```javascript
+const { analyzeCodeInMemory } = require('./scripts/hooks-system/infrastructure/ast/ast-core');
 
-* **Starting a new day/session** (fresh context)
-* **After pulling a lot of changes** (context drift prevention)
-* **After fixing blocking violations** (to refresh gate + evidence)
+const virtualFilePath = 'apps/backend/src/users/UserService.ts';
+const proposedCode = `
+export class UserService {
+  // ...
+}
+`;
 
-What it does:
+const result = analyzeCodeInMemory(proposedCode, virtualFilePath);
 
-* Detects active platforms (iOS/Android/Backend/Frontend)
-* Refreshes the evidence file (`.AI_EVIDENCE.json`)
-* Helps the AI gate operate deterministically (block/allow)
+if (result.hasCritical || result.hasHigh) {
+  throw new Error('BLOCKED: Critical/High violations detected');
+}
+```
 
-![ai-start execution example](docs/images/ai-start.png)
 ---
 
-## Installation & Lifecycle Commands
+## 7. MCP Integration
 
-### Update to latest version
+### 7.1 Purpose
 
-```bash
-npm install --save-dev @pumuki/ast-intelligence-hooks@latest
-npm run install-hooks
-````
+MCP provides a standard contract so agents can consume governance tools (gate and pre‑flight) before modifying the repository.
 
-### Uninstall
+### 7.2 Tools (blocking vs non‑blocking)
 
-```bash
-npm uninstall @pumuki/ast-intelligence-hooks
-```
+#### Blocking
 
-Legacy:
+- `ai_gate_check`
+- `pre_flight_check`
 
-```bash
-npm uninstall pumuki-ast-hooks
-```
+#### Non‑blocking
 
----
+- `read_platform_rules`
+- `set_human_intent`
+- `get_human_intent`
+- `clear_human_intent`
+- `suggest_human_intent`
+- `auto_execute_ai_start`
+- `check_evidence_status`
+- `validate_and_fix`
+- `sync_branches`
+- `cleanup_stale_branches`
+- `auto_complete_gitflow`
+- `record_test_created`
+- `reset_tdd_session`
 
-## Hook Installation & Management
+### 7.3 Blocking vs non‑blocking
 
-Install or update Git hooks (wizard-driven):
+Blocking tools return ALLOWED/BLOCKED and stop the flow if violations are detected.
 
-```bash
-npm run install-hooks
-```
+---
 
-(Equivalent to `npx ast-install`)
+## 8. Git Governance
 
----
+### 8.1 `ast:gitflow`
 
-## Operational Commands
+Automates the feature/fix → develop cycle.
 
-### Check installed version vs. latest published
+### 8.2 `ast:release`
 
-```bash
-npm run ast:check-version
-```
+Automates the develop → main release.
 
-### Run hook system with interactive menu
+### 8.3 Full Git Flow cycle
 
-```bash
-npx ast-hooks
-```
+The Git Flow cycle includes branch validation, commits, push, PR, merge (by policy), cleanup, and sync.
 
 ---
 
-## Manual Hook-System (Interactive Menu)
+## 9. Commands Section (MANDATORY – DO NOT CHANGE)
 
-Pumuki can be used fully manually (without waiting for Git hooks) via the interactive audit menu.
-
-### Recommended
+### Install (dev)
 
 ```bash
-npx ast-hooks
+npm install --save-dev @pumuki/ast-intelligence-hooks
 ```
 
-### Direct CLI (explicit)
+### Legacy install
 
 ```bash
-ast-hooks audit
+npm install --save-dev pumuki-ast-hooks
 ```
 
-### Run the orchestrator directly (local repository)
+### Update
 
 ```bash
-bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh
+npm install --save-dev @pumuki/ast-intelligence-hooks@latest
+npm run install-hooks
 ```
 
-### Non-interactive mode
-
-You can run specific audit modes without the menu:
+### Uninstall
 
 ```bash
-# Example: run AST Intelligence directly
-AUDIT_OPTION=7 bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh
-
-# Example: analyze staged files only (pre-commit equivalent)
-AUDIT_OPTION=3 bash scripts/hooks-system/infrastructure/shell/orchestrators/audit-orchestrator.sh
+npm uninstall @pumuki/ast-intelligence-hooks
 ```
 
-If defined as scripts:
+### Install hooks
 
 ```bash
-npm run ast:gitflow   # guided Git flow
-npm run ast:release   # guided release flow (develop → main)
-npm run ast:audit     # direct audit
+npm run install-hooks
 ```
 
----
-
-## Git Governance & Flow Automation
-
-Pumuki includes first-class Git governance commands to enforce a consistent workflow across teams and repositories.
-
-### Daily Development Flow
+### Run interactive menu
 
 ```bash
-npm run ast:gitflow
+npx ast-hooks
 ```
 
-With optional auto-merge:
+### Version check
 
 ```bash
-npm run ast:gitflow -- --auto-merge
+npm run ast:check-version
 ```
 
-### Release Flow (develop → main)
+### Audit
 
 ```bash
-npm run ast:release
+npm run audit
 ```
 
-With optional auto-merge:
+### Git flow
 
 ```bash
-npm run ast:release -- --auto-merge
+npm run ast:gitflow
 ```
 
-### Git Flow Cycle (ast:gitflow)
-
-Pumuki runs a complete Git Flow cycle:
-
-* Step 1: Validate Branch (must be feature/, fix/, etc.)
-* Step 2: Commit Changes (if uncommitted)
-* Step 3: Push to Origin
-* Step 4: Create Pull Request
-* Step 5: Merge Pull Request (optional)
-* Step 6: Cleanup Merged Branches
-* Step 7: Sync Branches
-* Git Flow Cycle Complete
-
-### Options
+### Release
 
 ```bash
-npm run ast:gitflow
-npm run ast:gitflow -- -m "feat: new feature"
-npm run ast:gitflow -- --auto-merge
-npm run ast:gitflow -- --skip-cleanup
-npm run ast:gitflow -- --skip-sync
+npm run ast:release
 ```
 
----
-
-## Evidence Guard (Daemon)
-
-The evidence guard ensures AI evidence freshness during long work sessions.
+### Guard start/stop/status/logs
 
 ```bash
 npm run ast:guard:start
 npm run ast:guard:stop
-npm run ast:guard:restart
 npm run ast:guard:status
 npm run ast:guard:logs
 ```
 
----
-
-## Developer Experience: Notifications & Guardrails
-
-Pumuki includes a built-in notification and guardrail layer to keep long work sessions safe and predictable.
-
-### macOS Notifications
-
-On macOS, notifications are delivered using:
-
-* `terminal-notifier` (preferred, if installed)
-* `osascript` fallback (built-in)
-
-The notification system includes deduplication, cooldowns, and retry logic to avoid spam during long sessions.
-
-### Evidence Freshness Alerts (SLA)
-
-When `.AI_EVIDENCE.json` becomes stale beyond the configured threshold, the guard will:
-
-* Notify that evidence is stale (including how many seconds)
-* Optionally attempt an auto-refresh depending on guard configuration
-
-When evidence returns to a fresh state (back within SLA), the guard can notify that evidence is healthy again.
-
-### AI Evidence Refresh Notifications
-
-When evidence is refreshed, the orchestration layer updates `.AI_EVIDENCE.json` and sends a macOS notification:
-
-* If gate is **ALLOWED**: `AI Evidence has been refreshed automatically`
-* If gate is **BLOCKED**: `AI Gate BLOCKED - <N> violations need fixing`
+### Evidence refresh
 
-### Git Tree Guardrails (Atomic Commits)
-
-Pumuki monitors the working tree and staging area and can notify when there are too many changes at once.
-
-Typical behavior:
-
-* Warn/error when the git tree exceeds configured limits (total/staged/unstaged)
-* Suggest splitting work into smaller, atomic commits
-* Provide grouped commit suggestions when it can infer feature-based groupings
-
-Configuration (environment variables):
+```bash
+npm run ast:refresh
+```
 
-* `HOOK_GUARD_DIRTY_TREE_STAGED_LIMIT` (default: 10)
-* `HOOK_GUARD_DIRTY_TREE_UNSTAGED_LIMIT` (default: 15)
-* `HOOK_GUARD_DIRTY_TREE_TOTAL_LIMIT` (default: 20)
-* `HOOK_GUARD_DIRTY_TREE_INTERVAL` (default: 60000 ms)
-* `HOOK_GUARD_DIRTY_TREE_REMINDER` (default: 300000 ms)
+---
 
-### Failure Modes (Visibility)
+## 10. IDE Compatibility Matrix
 
-If the framework cannot read or parse `.AI_EVIDENCE.json`, evidence reads will safely fail (returning `null`) and the guard will record debug entries to help diagnose the issue.
+| IDE | Hook Support | Blocks Before Write? | Fallback |
+| --- | --- | --- | --- |
+| Windsurf | `pre_write_code` | Yes | Git pre-commit |
+| Claude Code | `PreToolUse` (Write/Edit/MultiEdit) | Yes | Git pre-commit |
+| OpenCode | `tool.execute.before` | Yes | Git pre-commit |
+| Cursor | Post-write (`afterFileEdit`) | No | Git pre-commit |
+| Codex CLI | Approval policies only | Manual | Git pre-commit |
+| Kilo Code | Not documented | No | Git pre-commit |
 
 ---
 
-## Evidence Maintenance
-
-Manually refresh AI evidence:
+## 11. Typical Enterprise Use Cases
 
-```bash
-npm run ast:refresh
-```
+- Long‑running feature development with AI assistance.
+- Regulated systems where traceability and control are mandatory.
+- Platform teams governing multiple repositories.
+- Monorepos and multi‑team repositories with architecture drift risk.
 
 ---
 
-## Daily Workflow (High Level)
-
-## Maturity & Stability
+## 12. Intended Audience
 
-* Production usage
-* CI/CD integration
-* Changelog-driven evolution
-* Designed for long-lived codebases
+Designed for:
 
-Frequent updates are expected and encouraged at this stage.
+- senior engineers;
+- software architects;
+- platform teams;
+- teams responsible for SDLC quality, security, and governance.
 
 ---
 
-## Intended Audience
-
-Pumuki is intentionally opinionated and designed for:
-
-* Senior engineers
-* Tech leads
-* Software architects
-* Platform and infrastructure teams
+## 13. Maturity & Stability
 
-It is not optimized for casual or experimental AI usage.
+Production‑ready, version‑evolving, and designed for CI/CD integration.
 
 ---
 
-## License
+## 14. License
 
-© Pumuki 2025. All rights reserved.
+MIT