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.
npm install pumuki-ast-hooks

Portable, project‑agnostic, multi‑platform enterprise framework to govern AI‑assisted development through AST analysis, deterministic evidence, AI Gate controls, and operational automation.
Latest release: 6.3.3 (2026-01-28)
---
``bash`
git init
npm install --save-dev pumuki-ast-hooks
npx ast-install
npx ast-hooks audit
Default installation mode: npm-runtime.
To use the embedded runtime (vendored mode):
`bash`
HOOK_INSTALL_MODE=vendored npx ast-install
---
The framework includes an interactive audit menu that drives the orchestrator (full audit, strict modes, pattern checks, ESLint suites, AST intelligence, export, etc.).
`bash`
npx ast-hooks
Documentation:
- docs/USAGE.md (Interactive Menu, non‑interactive AUDIT_OPTION, and typical flows)CHANGELOG.md
- (Release notes and changes)docs/RELEASE_NOTES.md
- (Historical release notes)
---
!AST Intelligence System Overview
!AST Intelligence Audit - Part 1
!AST Intelligence Audit - Part 2
!AST Intelligence Audit - Part 3
---
Pumuki AST Intelligence Framework
Enterprise governance for AI‑assisted development: persistent evidence, deterministic gate, and multi‑platform AST enforcement.
---
Pumuki AST Intelligence Framework is a portable, project‑agnostic framework for long‑lived systems that governs AI‑assisted work by combining:
- 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.
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:
- architecture drift;
- silent introduction of anti‑patterns;
- security degradation;
- accumulation of technical debt;
- loss of traceability.
Pumuki introduces control and operational reproducibility: it does not rely on “conversation”, it relies on evidence and enforcement.
Without governance, AI:
- 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.
Pumuki exists to make AI usage compatible with enterprise engineering standards.
Operational reliability is not achieved with prompts. It is achieved with:
- persistent, auditable evidence;
- formal rules per platform;
- deterministic enforcement;
- early blocking of critical violations.
---
Decisions are made based on a persistent evidence file (.AI_EVIDENCE.json), not chat memory.
Before any AI‑assisted operation, repository state and evidence are validated. If it does not comply, the operation is blocked.
Rules run on real ASTs and code structure, avoiding fragile approximations.
Pumuki blocks as early as possible: pre‑write, pre‑commit, and CI.
A single enforcement model governs iOS, Android, backend, and frontend.
This framework treats token usage as an operational cost.
- Batch checks and avoid redundant scans.
- Reuse cached context when safe.
- Ask the user for missing info instead of exploring blindly.
- Keep responses concise.
This principle is part of the framework contract and is surfaced to agents via:
- ai_gate_check → mandatory_rules.framework_rulespre_flight_check
- → framework_rules
---
.AI_EVIDENCE.json is the persistent source of truth. It represents the governance state and enables reproducible decisions.
It includes:
- session and branch context;
- violations by severity;
- gate state;
- detected platforms;
- operational watchers;
- cognitive layers.
The AI Gate decides:
- ALLOWED: proceed (following rules).
- BLOCKED: the operation is blocked with actionable feedback.
Enforcement happens in layers:
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.
#### Human Intent (Intentional Memory)
Defines the human goal, constraints, and expiration.
#### Semantic Snapshot (Semantic Memory)
Summarizes project state (health, active platforms, gate state) to prevent drift.
---
Multi‑platform AST‑based analysis:
- iOS (Swift)
- Android (Kotlin)
- Backend (Node.js / NestJS)
- Frontend (React / Next.js)
Block before writing when the IDE can intercept operations.
Validation over proposed code as a string (without writing to disk).
IDE integrations to intercept changes before writing (or fallback via Git).
MCP server for agents with blocking and non‑blocking tools.
Universal Git‑level enforcement (pre‑commit / pre‑push) to prevent violations from entering history.
Automation of feature/fix cycles and releases.
Operational notifications for gate, evidence, health, guard, and tokens.
Guard/daemon to keep evidence fresh and reduce drift during long sessions. Automatically refreshes evidence every 3 minutes during active development sessions, independent of commits or manual triggers.
Apply the same rules in pipelines.
---
Analyzes code before writing it to disk. This prevents dangerous or degrading patterns from even entering the working tree.
When the IDE supports pre‑write hooks, the framework intercepts edit/write operations and validates the final content.
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.
If CRITICAL/HIGH violations exist, the operation is blocked.
`javascript
const { analyzeCodeInMemory } = require('./scripts/hooks-system/infrastructure/ast/ast-core');
const virtualFilePath = 'apps/backend/src/users/UserService.ts';
const proposedCode =
export class UserService {
// ...
};
const result = analyzeCodeInMemory(proposedCode, virtualFilePath);
if (result.hasCritical || result.hasHigh) {
throw new Error('BLOCKED: Critical/High violations detected');
}
`
---
MCP provides a standard contract so agents can consume governance tools (gate and pre‑flight) before modifying the repository.
#### Blocking
- ai_gate_checkpre_flight_check
-
#### Non‑blocking
- read_platform_rulesset_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
-
Blocking tools return ALLOWED/BLOCKED and stop the flow if violations are detected.
---
Automates the feature/fix → develop cycle.
Automates the develop → main release.
The Git Flow cycle includes branch validation, commits, push, PR, merge (by policy), cleanup, and sync.
---
`bash`
npm install --save-dev pumuki-ast-hooks
npx ast-install
`bash`
npm install --save-dev pumuki-ast-hooks
npx ast-install
`bash`
npm install --save-dev pumuki-ast-hooks@latest
npx ast-install
`bash`
npx ast-uninstall
npm uninstall pumuki-ast-hooks
`bash`
npm run install-hooks
`bash`
npx ast-hooks
`bash`
npm run ast:check-version
`bash`
npm run audit
`bash`
npm run ast:gitflow
`bash`
npm run ast:release
`bash`
npm run ast:guard:start
npm run ast:guard:stop
npm run ast:guard:status
npm run ast:guard:logs
`bash`
npm run ast:refresh
npx ast-hooks evidence:full-update
bash scripts/hooks-system/bin/update-evidence.sh
---
| IDE | Hook Support | Blocks Before Write? | Fallback |
| --- | --- | --- | --- |
| Windsurf | pre_write_code | Yes | Git pre-commit |PreToolUse
| Claude Code | (Write/Edit/MultiEdit) | Yes | Git pre-commit |tool.execute.before
| OpenCode | | Yes | Git pre-commit |afterFileEdit
| Cursor | Post-write () | No | Git pre-commit |
| Codex CLI | Approval policies only | Manual | Git pre-commit |
| Kilo Code | Not documented | No | Git pre-commit |
---
)Use config/ast-exclusions.json to suppress specific rules for specific files.
Example:
`json`
{
"exclusions": {
"rules": {
"ios.solid.dip.concrete_dependency": {
"files": [
"apps/ios/Infrastructure/Repositories/Auth/AuthLoginRepositoryImpl.swift"
],
"excludePatterns": [
"*/AuthRepository.swift"
]
}
}
}
}
Rules without files/paths/globs` are treated as global exclusions.
---
- 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.
---
Designed for:
- senior engineers;
- software architects;
- platform teams;
- teams responsible for SDLC quality, security, and governance.
---
Production‑ready, version‑evolving, and designed for CI/CD integration.
---
MIT