Pumuki AST Intelligence Framework

Portable, project‑agnostic, multi‑platform enterprise framework to govern AI‑assisted development through AST analysis, deterministic evidence, AI Gate controls, and operational automation.

!npm
!node
!platforms
!license

Latest release: 6.3.3 (2026-01-28)

---

Quick start (30–60s)

``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
`

---

Operational visuals (examples)

$3

!Pre-write hook output

$3

!AI Gate blocked example

$3

!ai-start output

$3

!pre-flight-check output

$3

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)

---

Visual Overview

!AST Intelligence System Overview

!AST Intelligence Workflow

!AST Intelligence Audit - Part 1

!AST Intelligence Audit - Part 2

!AST Intelligence Audit - Part 3

---

1. Identity

$3

Pumuki AST Intelligence Framework

$3

Enterprise governance for AI‑assisted development: persistent evidence, deterministic gate, and multi‑platform AST enforcement.

---

2. Clear definition

$3

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.

$3

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.

$3

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.

$3

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.

---

3. Core principles

$3

Decisions are made based on a persistent evidence file (.AI_EVIDENCE.json), not chat memory.

$3

Before any AI‑assisted operation, repository state and evidence are validated. If it does not comply, the operation is blocked.

$3

Rules run on real ASTs and code structure, avoiding fragile approximations.

$3

Pumuki blocks as early as possible: pre‑write, pre‑commit, and CI.

$3

A single enforcement model governs iOS, Android, backend, and frontend.

$3

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_rules
- pre_flight_check → framework_rules

---

4. Architecture and mental model

$3

.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.

$3

The AI Gate decides:

- ALLOWED: proceed (following rules).
- BLOCKED: the operation is blocked with actionable feedback.

$3

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.

$3

#### 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.

---

5. Features (complete)

$3

Multi‑platform AST‑based analysis:

- iOS (Swift)
- Android (Kotlin)
- Backend (Node.js / NestJS)
- Frontend (React / Next.js)

$3

Block before writing when the IDE can intercept operations.

$3

Validation over proposed code as a string (without writing to disk).

$3

IDE integrations to intercept changes before writing (or fallback via Git).

$3

MCP server for agents with blocking and non‑blocking tools.

$3

Universal Git‑level enforcement (pre‑commit / pre‑push) to prevent violations from entering history.

$3

Automation of feature/fix cycles and releases.

$3

Operational notifications for gate, evidence, health, guard, and tokens.

$3

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.

$3

Apply the same rules in pipelines.

---

6. Pre‑Write Enforcement

$3

Analyzes code before writing it to disk. This prevents dangerous or degrading patterns from even entering the working tree.

$3

When the IDE supports pre‑write hooks, the framework intercepts edit/write operations and validates the final content.

$3

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.

$3

If CRITICAL/HIGH violations exist, the operation is blocked.

$3

`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');
}
`

---

7. MCP Integration

$3

MCP provides a standard contract so agents can consume governance tools (gate and pre‑flight) before modifying the repository.

$3

#### Blocking

- ai_gate_check
- pre_flight_check

#### 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

$3

Blocking tools return ALLOWED/BLOCKED and stop the flow if violations are detected.

---

8. Git Governance

$3

Automates the feature/fix → develop cycle.

$3

Automates the develop → main release.

$3

The Git Flow cycle includes branch validation, commits, push, PR, merge (by policy), cleanup, and sync.

---

9. Commands (required)

$3

`bash
npm install --save-dev pumuki-ast-hooks
npx ast-install
`

$3

`bash
npm install --save-dev pumuki-ast-hooks
npx ast-install
`

$3

`bash
npm install --save-dev pumuki-ast-hooks@latest
npx ast-install
`

$3

`bash
npx ast-uninstall
npm uninstall pumuki-ast-hooks
`

$3

`bash
npm run install-hooks
`

$3

`bash
npx ast-hooks
`

$3

`bash
npm run ast:check-version
`

$3

`bash
npm run audit
`

$3

`bash
npm run ast:gitflow
`

$3

`bash
npm run ast:release
`

$3

`bash
npm run ast:guard:start
npm run ast:guard:stop
npm run ast:guard:status
npm run ast:guard:logs
`

$3

`bash
npm run ast:refresh
npx ast-hooks evidence:full-update
bash scripts/hooks-system/bin/update-evidence.sh
`

---

10. IDE Compatibility Matrix

| 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 |

---

10. Rule Exclusions (ast-exclusions.json)

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.

---

11. Typical Enterprise Use Cases

- 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.

---

12. Intended Audience

Designed for:

- senior engineers;
- software architects;
- platform teams;
- teams responsible for SDLC quality, security, and governance.

---

13. Maturity & Stability

Production‑ready, version‑evolving, and designed for CI/CD integration.

---

14. License

MIT