pumuki 6.3.8 → 6.3.10

package/README.md

@@ -1,6 +1,6 @@
 # Pumuki AST Intelligence Framework
 
-[![Version](https://img.shields.io/badge/version-6.3.7-1d4ed8)](package.json)
+[![Version](https://img.shields.io/npm/v/pumuki?color=1d4ed8)](https://www.npmjs.com/package/pumuki)
 [![License](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
 [![Build](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-0ea5e9)](package.json)
@@ -8,49 +8,51 @@
 
 <img src="assets/logo.png" alt="Pumuki" width="100%" />
 
-Enterprise governance for AI-assisted code delivery.
+Deterministic governance for AI-assisted software delivery.
 
-Pumuki turns code changes into traceable and reproducible decisions:
+Pumuki converts code changes into traceable, reproducible decisions:
 
 `Facts -> Rules -> Gate -> ai_evidence v2.1`
 
-This gives enterprise teams one deterministic source of truth to decide what is blocked, what is warned, and why, both locally and in CI.
-
-## Table of contents
-
-- [Why Pumuki](#why-pumuki)
-- [Quick Start](#quick-start)
-- [Automated vs Manual Operations](#automated-vs-manual-operations)
-- [Software Lifecycle](#software-lifecycle)
-- [Command Reference](#command-reference)
-- [MCP: JSON Installation and Configuration](#mcp-json-installation-and-configuration)
-- [Architecture and Design Philosophy](#architecture-and-design-philosophy)
+## Table of Contents
+
+- [Overview](#overview)
+- [Capabilities](#capabilities)
+- [Quick Start for Consumer Repositories](#quick-start-for-consumer-repositories)
+- [Lifecycle Commands](#lifecycle-commands)
+- [Gate Commands](#gate-commands)
+- [Architecture and Policy Model](#architecture-and-policy-model)
+- [MCP Evidence Context Server (Optional)](#mcp-evidence-context-server-optional)
+- [Framework Development (This Repository)](#framework-development-this-repository)
+- [Deterministic Validation Suite](#deterministic-validation-suite)
+- [Troubleshooting](#troubleshooting)
 - [Contributing and Support](#contributing-and-support)
 - [References](#references)
 
-## Why Pumuki
+## Overview
+
+Pumuki is a provider-agnostic framework for enforcing deterministic quality gates across multi-platform repositories.
 
-### Real problem in large teams
+It is designed for enterprise teams that need:
 
-- Inconsistent quality checks between local and CI.
-- Hard-to-audit technical decisions.
-- Configuration drift across platforms.
-- Operational incidents without reproducible evidence.
+- consistent gate behavior across local and CI,
+- auditable decisions backed by deterministic evidence,
+- versioned and lockable rule packs,
+- operational runbooks for incidents and rollout management.
 
-### What Pumuki solves
+Canonical npm package name: `pumuki`.
 
-- Stage-aware gate policies (`PRE_COMMIT`, `PRE_PUSH`, `CI`).
-- Versioned and locked rule bundles (`skills.lock.json`).
-- Deterministic evidence contract (`.ai_evidence.json`).
-- Operational runbooks for triage, closure, and handoff.
+Legacy package `pumuki-ast-hooks` is deprecated and frozen at `6.3.7`.
 
-### Where it fits best
+## Capabilities
 
-- Multi-platform repositories (`ios`, `backend`, `frontend`, `android`).
-- Teams with compliance/audit requirements.
-- High-change environments with AI-assisted development.
+- Stage-aware gate policies: `PRE_COMMIT`, `PRE_PUSH`, `CI`.
+- Multi-platform detection and combined evaluation: iOS, Backend, Frontend, Android.
+- Rules + overrides with locked baseline semantics.
+- Deterministic evidence (`.ai_evidence.json`) for machine and human workflows.
+- Optional read-only MCP evidence server for agent consumption.
 
-## Quick Start
+## Quick Start for Consumer Repositories
 
 ### Prerequisites
 
@@ -58,308 +60,195 @@ This gives enterprise teams one deterministic source of truth to decide what is
 - `npm >= 9.0.0`
 - `git`
 
-### Installation
+### 1) Install
 
 ```bash
-git clone https://github.com/SwiftEnProfundidad/ast-intelligence-hooks.git
-cd ast-intelligence-hooks
-npm ci
+npm install --save-exact pumuki
 ```
 
-### Minimal verification
+### 2) Install managed hooks in your repository
+
+Run from the target repository root:
 
 ```bash
-npm run typecheck
-npm run test:deterministic
-npm run validation:package-manifest
+npx pumuki install
 ```
 
-### First run
+### 3) Verify lifecycle status
 
 ```bash
-npm run framework:menu
+npx pumuki doctor
+npx pumuki status
 ```
 
-## Automated vs Manual Operations
-
-### Automated path (default)
-
-The core lifecycle is automated:
-
-- facts extraction,
-- rules evaluation,
-- stage-aware gate decision,
-- `ai_evidence v2.1` generation,
-- CI workflow execution.
-
-### Manual path (intentional)
-
-`validation:*` commands are operational controls for:
-
-- triage,
-- closure,
-- handoff,
-- adapter diagnostics,
-- rollout guardrails.
-
-Examples:
-
-- `validation:consumer-startup-triage`
-- `validation:phase5-execution-closure`
-- `validation:phase8:*`
-- `validation:adapter-*`
+### 4) Run stage gates manually (optional)
 
-Practical rule:
+```bash
+npx pumuki-pre-commit
+npx pumuki-pre-push
+npx pumuki-ci
+```
 
-- normal development: automated pipeline + tests,
-- incident/rollout handling: manual runbook commands.
+### 5) Expected outputs
 
-## Software Lifecycle
+- Gate exit code: `0` (allow) or `1` (block).
+- Deterministic evidence file: `.ai_evidence.json`.
 
-### Consumer package install (enterprise UX)
+### Update and remove
 
 ```bash
-npm install --save-exact pumuki
 npm update pumuki
-npm uninstall pumuki
-```
-
-`npm upgrade pumuki` is also supported as an alias to update in npm environments where `upgrade` is mapped.
+npx pumuki update --latest
 
-### Installation (fresh setup)
-
-```bash
-npm ci
-npm run typecheck
-npm run test:deterministic
-npm run skills:lock:check
+npx --yes pumuki remove
 ```
 
-### Upgrade
+`pumuki remove` performs managed uninstall + artifact purge in one command.
 
-```bash
-git pull
-npm ci
-npm run skills:lock:check
-npm run validation:docs-hygiene
-npm run test:deterministic
-```
+## Lifecycle Commands
 
-### Uninstall (local cleanup)
+The `pumuki` binary provides repository lifecycle operations:
 
-```bash
-rm -rf node_modules
-rm -rf .audit-reports
-```
-
-If legacy guards are active:
-
-```bash
-npm run ast:guard:stop
-```
+| Command | Purpose |
+| --- | --- |
+| `pumuki install` | Install managed `pre-commit` and `pre-push` hook blocks |
+| `pumuki uninstall --purge-artifacts` | Remove managed hooks and purge known artifacts |
+| `pumuki remove` | One-command cleanup + package uninstall in consumer repos |
+| `pumuki update --latest` | Update package and re-apply managed hooks |
+| `pumuki doctor` | Safety checks (hook drift, tracked `node_modules`, lifecycle state) |
+| `pumuki status` | Current lifecycle snapshot |
 
-For consumer repositories using the package:
+`pumuki remove` is dependency-safe by design: it never deletes non-Pumuki third-party dependencies.
 
-```bash
-npx --yes pumuki remove
-```
+## Gate Commands
 
-This command also prunes orphan `node_modules/.package-lock.json` residue when no installed modules remain.
+Dedicated gate binaries are available:
 
-### Dependency conflict troubleshooting
+| Binary | Stage |
+| --- | --- |
+| `pumuki-pre-commit` | `PRE_COMMIT` |
+| `pumuki-pre-push` | `PRE_PUSH` |
+| `pumuki-ci` | `CI` |
 
-| Symptom | Typical root cause | Recommended action |
-| --- | --- | --- |
-| local differs from CI | skills lock drift | `npm run skills:lock:check` |
-| `tsx` fails to start | incompatible Node runtime | upgrade to `Node >= 18` |
-| upgrade regressions | inconsistent lockfile/modules | `rm -rf node_modules package-lock.json && npm install` |
-| noisy docs/artifacts | stale `.audit-reports` outputs | `npm run validation:clean-artifacts -- --dry-run` |
+## Architecture and Policy Model
 
-## Command Reference
+### Deterministic pipeline
 
-Flag forwarding pattern:
+`Facts -> Rules -> Gate -> ai_evidence v2.1`
 
-```bash
-npm run <script> -- <flags>
-```
+- Facts are extracted from staged files or commit ranges.
+- Rules are evaluated with platform-aware packs and project overrides.
+- Gate applies stage policy thresholds.
+- Evidence is generated as deterministic, machine-readable contract.
 
-### Core, CLI, and framework
+### Default stage policies
 
-| Command | Description | Example |
-| --- | --- | --- |
-| `npm run install-hooks` | Install managed Pumuki hooks (`pre-commit`, `pre-push`) | `npm run install-hooks` |
-| `npm run check-version` | Print lifecycle/runtime status | `npm run check-version` |
-| `npm run pumuki:install` | Install managed hooks in current Git repo | `npm run pumuki:install` |
-| `npm run pumuki:uninstall` | Uninstall managed hooks and purge untracked Pumuki artifacts | `npm run pumuki:uninstall` |
-| `npm run pumuki:remove` | One-command cleanup + package removal from consumer repo | `npm run pumuki:remove` |
-| `npm run pumuki:update` | Update Pumuki dependency to latest and re-apply hooks | `npm run pumuki:update` |
-| `npm run pumuki:doctor` | Enterprise baseline safety checks (tracked `node_modules`, hook/state drift) | `npm run pumuki:doctor` |
-| `npm run pumuki:status` | Lifecycle status snapshot | `npm run pumuki:status` |
-| `npm run audit` | Run AST CLI | `npm run audit -- --help` |
-| `npm run ast` | AST CLI alias | `npm run ast -- --help` |
-| `npm run framework:menu` | Launch interactive operations menu | `npm run framework:menu` |
-| `npm run mcp:evidence` | Start read-only MCP evidence server | `npm run mcp:evidence` |
-| `npm run violations` | Violations CLI | `npm run violations -- --help` |
-| `npm run violations:list` | List violations | `npm run violations:list` |
-| `npm run violations:show` | Show one violation | `npm run violations:show -- <id>` |
-| `npm run violations:summary` | Aggregated violations summary | `npm run violations:summary` |
-| `npm run violations:top` | Top violations view | `npm run violations:top` |
-
-### Quality and testing
-
-| Command | Description | Example |
-| --- | --- | --- |
-| `npm run typecheck` | TypeScript check without emit | `npm run typecheck` |
-| `npm run test` | Main Jest test suite | `npm run test` |
-| `npm run test:evidence` | Evidence-specific tests | `npm run test:evidence` |
-| `npm run test:mcp` | MCP tests | `npm run test:mcp` |
-| `npm run test:heuristics` | AST heuristics tests | `npm run test:heuristics` |
-| `npm run test:stage-gates` | Stage policy/gate tests | `npm run test:stage-gates` |
-| `npm run test:deterministic` | Recommended deterministic baseline | `npm run test:deterministic` |
-| `npm run validation:package-manifest` | Validate package manifest contract | `npm run validation:package-manifest` |
-| `npm run validation:package-smoke` | Blocking package smoke test | `npm run validation:package-smoke` |
-| `npm run validation:package-smoke:minimal` | Minimal package smoke test | `npm run validation:package-smoke:minimal` |
-| `npm run validation:lifecycle-smoke` | Lifecycle smoke check (`install -> run -> uninstall` clean round-trip) | `npm run validation:lifecycle-smoke` |
-| `npm run validation:docs-hygiene` | Documentation guardrail checks | `npm run validation:docs-hygiene` |
-| `npm run validation:clean-artifacts -- --dry-run` | Simulated artifact cleanup | `npm run validation:clean-artifacts -- --dry-run` |
-| `npm run skills:compile` | Compile skills lock | `npm run skills:compile` |
-| `npm run skills:lock:check` | Verify skills lock freshness | `npm run skills:lock:check` |
-
-### Consumer diagnostics and support
-
-| Command | Main flags | Example |
+| Stage | Block on or above | Warn on or above |
 | --- | --- | --- |
-| `validation:consumer-ci-artifacts` | `--repo --limit --out` | `npm run validation:consumer-ci-artifacts -- --repo <owner>/<repo> --limit 20 --out .audit-reports/consumer-triage/consumer-ci-artifacts-report.md` |
-| `validation:consumer-ci-auth-check` | `--repo --out` | `npm run validation:consumer-ci-auth-check -- --repo <owner>/<repo> --out .audit-reports/consumer-triage/consumer-ci-auth-check.md` |
-| `validation:consumer-workflow-lint` | `--repo-path --actionlint-bin --out` | `npm run validation:consumer-workflow-lint -- --repo-path /path/repo --actionlint-bin /tmp/actionlint --out .audit-reports/consumer-triage/consumer-workflow-lint-report.md` |
-| `validation:consumer-support-bundle` | `--repo --limit --out` | `npm run validation:consumer-support-bundle -- --repo <owner>/<repo> --limit 20 --out .audit-reports/consumer-triage/consumer-startup-failure-support-bundle.md` |
-| `validation:consumer-support-ticket-draft` | `--repo --support-bundle --auth-report --out` | `npm run validation:consumer-support-ticket-draft -- --repo <owner>/<repo> --support-bundle .audit-reports/consumer-triage/consumer-startup-failure-support-bundle.md --auth-report .audit-reports/consumer-triage/consumer-ci-auth-check.md --out .audit-reports/consumer-triage/consumer-support-ticket-draft.md` |
-| `validation:consumer-startup-unblock-status` | `--repo --support-bundle --auth-report --workflow-lint-report --out` | `npm run validation:consumer-startup-unblock-status -- --repo <owner>/<repo> --support-bundle .audit-reports/consumer-triage/consumer-startup-failure-support-bundle.md --auth-report .audit-reports/consumer-triage/consumer-ci-auth-check.md --workflow-lint-report .audit-reports/consumer-triage/consumer-workflow-lint-report.md --out .audit-reports/consumer-triage/consumer-startup-unblock-status.md` |
-| `validation:consumer-startup-triage` | `--repo --out-dir [--skip-workflow-lint]` | `npm run validation:consumer-startup-triage -- --repo SwiftEnProfundidad/pumuki-actions-healthcheck-temp --out-dir .audit-reports/consumer-triage-temp --skip-workflow-lint` |
+| `PRE_COMMIT` | `CRITICAL` | `ERROR` |
+| `PRE_PUSH` | `ERROR` | `WARN` |
+| `CI` | `ERROR` | `WARN` |
 
-### Phase 5 (closure and handoff)
+### Platform detection selectors
 
-| Command | Main flags | Example |
-| --- | --- | --- |
-| `validation:phase5-blockers-readiness` | `--consumer-triage-report --out [--require-adapter-report --adapter-report]` | `npm run validation:phase5-blockers-readiness -- --consumer-triage-report .audit-reports/consumer-triage/consumer-startup-triage-report.md --out .audit-reports/phase5/phase5-blockers-readiness.md` |
-| `validation:phase5-execution-closure-status` | `--phase5-blockers-report --consumer-unblock-report --out` | `npm run validation:phase5-execution-closure-status -- --phase5-blockers-report .audit-reports/phase5/phase5-blockers-readiness.md --consumer-unblock-report .audit-reports/consumer-triage/consumer-startup-unblock-status.md --out .audit-reports/phase5/phase5-execution-closure-status.md` |
-| `validation:phase5-execution-closure` | `--repo --out-dir [--mock-consumer] [--skip-workflow-lint] [--skip-auth-preflight]` | `npm run validation:phase5-execution-closure -- --repo SwiftEnProfundidad/pumuki-actions-healthcheck-temp --out-dir .audit-reports/phase5 --mock-consumer` |
-| `validation:phase5-external-handoff` | `--repo [--require-mock-ab-report] [--require-artifact-urls] [--artifact-url] [--out]` | `npm run validation:phase5-external-handoff -- --repo SwiftEnProfundidad/pumuki-actions-healthcheck-temp --require-mock-ab-report` |
-| `validation:phase5-latest:refresh` | shell script | `npm run validation:phase5-latest:refresh` |
-| `validation:phase5-latest:sync-docs` | shell script | `npm run validation:phase5-latest:sync-docs` |
-| `validation:phase5-latest:ready-check` | shell script | `npm run validation:phase5-latest:ready-check` |
-| `validation:phase5-post-support:refresh` | shell script | `npm run validation:phase5-post-support:refresh` |
-
-### Phase 8 (operations, anti-loop, status)
-
-| Command | Main flags | Example |
-| --- | --- | --- |
-| `validation:phase8:resume-after-billing` | shell script | `npm run validation:phase8:resume-after-billing` |
-| `validation:phase8:next-step` | shell script | `npm run validation:phase8:next-step` |
-| `validation:phase8:doctor` | shell script | `npm run validation:phase8:doctor` |
-| `validation:phase8:autopilot` | shell script | `npm run validation:phase8:autopilot` |
-| `validation:phase8:status-pack` | shell script | `npm run validation:phase8:status-pack` |
-| `validation:phase8:tick` | shell script | `npm run validation:phase8:tick` |
-| `validation:phase8:loop-guard` | shell script | `npm run validation:phase8:loop-guard` |
-| `validation:phase8:loop-guard-coverage` | shell script | `npm run validation:phase8:loop-guard-coverage` |
-| `validation:phase8:mark-followup-state` | `<ticket_id> <posted_by> <POSTED_WAITING_REPLY|SUPPORT_REPLIED> [posted_at] [reply_at] [summary]` | `npm run validation:phase8:mark-followup-state -- 4077449 juancarlosmerlosalbarracin POSTED_WAITING_REPLY` |
-| `validation:phase8:mark-followup-posted-now` | `<posted_by> [ticket_id] [posted_at]` | `npm run validation:phase8:mark-followup-posted-now -- juancarlosmerlosalbarracin 4077449` |
-| `validation:phase8:mark-followup-replied-now` | `<posted_by> <summary> [ticket_id] [posted_at] [reply_at]` | `npm run validation:phase8:mark-followup-replied-now -- juancarlosmerlosalbarracin "support replied" 4077449` |
-| `validation:phase8:ready-handoff` | shell script | `npm run validation:phase8:ready-handoff` |
-| `validation:phase8:close-ready` | shell script | `npm run validation:phase8:close-ready` |
-
-### Adapter readiness and legacy compatibility
-
-| Command | Description |
+| Platform | Detection selector |
 | --- | --- |
-| `validation:adapter-session-status` | Build adapter session status report |
-| `validation:adapter-real-session-report` | Build adapter real-session report |
-| `validation:adapter-readiness` | Build final adapter readiness report |
-| `validate:adapter-hooks-local` | Validate legacy local adapter runtime |
-| `print:adapter-hooks-config` | Print legacy adapter hook config |
-| `install:adapter-hooks-config` | Install legacy adapter hook config |
-| `verify:adapter-hooks-runtime` | Verify legacy adapter runtime |
-| `assess:adapter-hooks-session` | Assess legacy adapter session |
-| `assess:adapter-hooks-session:any` | Assess legacy adapter session including simulated events |
+| iOS | `*.swift` |
+| Backend | `apps/backend/**/*.ts` |
+| Frontend | `apps/frontend/**/*.{ts,tsx,js,jsx}` and `apps/web/**/*.{ts,tsx,js,jsx}` |
+| Android | `*.kt`, `*.kts` |
 
-## MCP: JSON Installation and Configuration
+## MCP Evidence Context Server (Optional)
 
-### Is MCP mandatory to use Pumuki?
+MCP is optional. Pumuki core does not depend on MCP.
 
-No.
+### Consumer repository usage
 
-- Pumuki core does not require MCP JSON registration.
-- MCP is optional and only needed for external MCP/agent clients.
-
-### MCP JSON example
+Use the published binary from npm:
 
 ```json
 {
   "mcpServers": {
     "pumuki-evidence": {
-      "command": "npm",
-      "args": ["run", "mcp:evidence"],
-      "cwd": "/absolute/path/to/ast-intelligence-hooks"
+      "command": "npx",
+      "args": ["--yes", "pumuki-mcp-evidence"],
+      "cwd": "/absolute/path/to/your-consumer-repo"
     }
   }
 }
 ```
 
-Start locally:
+### Framework repository usage
+
+If you are developing this framework locally:
 
 ```bash
 npm run mcp:evidence
 ```
 
-## Architecture and Design Philosophy
+## Framework Development (This Repository)
 
-### Deterministic architecture
+Use this path only when working on Pumuki itself (not as a consumer).
 
-`Facts -> Rules -> Gate -> ai_evidence v2.1`
-
-This deterministic flow is the backbone of reproducibility and governance.
-
-### Stage-aware policy model
+```bash
+git clone https://github.com/SwiftEnProfundidad/ast-intelligence-hooks.git
+cd ast-intelligence-hooks
+npm ci
+```
 
-Each stage has an explicit tolerance profile:
+Recommended maintainer baseline:
 
-- `PRE_COMMIT`: immediate developer feedback,
-- `PRE_PUSH`: stronger repository-level protection,
-- `CI`: strict release-grade enforcement.
+```bash
+npm run typecheck
+npm run test
+npm run test:deterministic
+npm run validation:package-manifest
+npm run skills:lock:check
+```
 
-### Platform-aware by default
+Operational menu:
 
-Pumuki detects platform scope and applies relevant packs:
+```bash
+npm run framework:menu
+```
 
-- iOS,
-- Backend,
-- Frontend,
-- Android.
+## Deterministic Validation Suite
 
-### Rule-pack governance
+Core validation commands used by maintainers:
 
-- Rule packs are versioned.
-- Skills bundles are locked.
-- Drift detection is first-class.
+| Command | Purpose |
+| --- | --- |
+| `npm run test:deterministic` | Evidence + MCP + heuristics deterministic baseline |
+| `npm run validation:package-manifest` | Package contract and publish guardrails |
+| `npm run validation:package-smoke` | Blocking install/lifecycle smoke in temp consumer |
+| `npm run validation:package-smoke:minimal` | Minimal smoke path |
+| `npm run validation:lifecycle-smoke` | Lifecycle round-trip check |
+| `npm run validation:docs-hygiene` | Documentation governance checks |
+| `npm run validation:clean-artifacts -- --dry-run` | Preview cleanup of generated artifacts |
 
-### Evidence-first operations
+## Troubleshooting
 
-Operational decisions are backed by deterministic artifacts, not tribal memory.
+| Symptom | Typical cause | Action |
+| --- | --- | --- |
+| Gate behaves differently in local and CI | Skills lock or policy drift | `npm run skills:lock:check` |
+| `tsx` runtime errors | Unsupported Node runtime | Upgrade to `Node >= 18` |
+| Upgrade side effects | Inconsistent modules/lockfile state | `rm -rf node_modules package-lock.json && npm install` |
+| Consumer repo still has artifacts after tests | Lifecycle was not removed | `npx --yes pumuki remove` |
 
 ## Contributing and Support
 
 ### Contributing
 
 1. Branch from `develop`.
-2. Keep changes scoped and deterministic.
-3. Update docs/runbooks when behavior changes.
-4. Open a PR with clear context and impact.
+2. Keep changes deterministic and scoped.
+3. Update docs and runbooks when behavior changes.
+4. Open PR with impact, risk, and verification notes.
 
-### Issues and support
+### Support
 
-- Bug reports: open a GitHub issue with reproducible context.
-- Operational incidents: use `docs/validation/*` runbooks and artifacts.
-- Architecture questions: start from `docs/ARCHITECTURE.md` and `docs/evidence-v2.1.md`.
+- Product and bug issues: GitHub issues.
+- Operational incidents: `docs/validation/*` runbooks.
+- Architecture references: `docs/ARCHITECTURE.md` and `docs/evidence-v2.1.md`.
 
 ## References
 

package/VERSION

@@ -1 +1 @@
-v6.3.3
+v6.3.10

package/docs/REFRACTOR_PROGRESS.md

@@ -148,7 +148,17 @@ Estado consolidado del refactor con seguimiento de tareas y evidencia del avance
 - ✅ Completar `pumuki-mock-consumer` con escenarios reproducibles multi-plataforma (`clean`, `violations`, `mixed`) y script de aplicación de escenarios.
 - ✅ Unificar iOS del mock exclusivamente bajo `apps/ios/` (eliminando duplicación `ios/`) para mantener estructura homogénea `apps/*`.
 - ✅ Migrar nombre canónico del paquete a `pumuki` y alinear comandos enterprise cortos (`npm install/update/uninstall pumuki`) con documentación y validaciones.
-- 🚧 Ejecutar matriz E2E completa en `pumuki-mock-consumer` (`install -> pre-commit/pre-push/ci -> remove`) sobre escenarios `clean`, `violations` y `mixed`.
+- ✅ Publicar `pumuki@6.3.8` en npm y alinear tags de distribución (`latest` y `next`) a la misma versión.
+- ✅ Marcar `pumuki-ast-hooks` como paquete npm legacy/deprecado y documentar migración explícita en `README.md`.
+- ✅ Corregir `Quick Start` del `README.md` para consumo real por npm (`pumuki`) y comandos ejecutables de lifecycle/gates.
+- ✅ Auditar `README.md` con criterios enterprise (profesionalismo, claridad, estructura y completitud) y generar backlog de mejoras priorizado.
+- ✅ Reescribir `README.md` de forma integral con estándar enterprise (audiencia consumer/framework separada, comandos reales y estructura consistente).
+- ✅ Publicar `pumuki@6.3.9` en npm (tags `latest` y `next`) para reflejar la documentación enterprise reescrita.
+- ✅ Ejecutar matriz E2E completa en `pumuki-mock-consumer` (`install -> pre-commit/pre-push/ci -> remove`) sobre escenarios `clean`, `violations` y `mixed`.
+- ✅ Endurecer `pumuki-mock-consumer` con fixtures multiarchivo por plataforma y runner único `npm run pumuki:matrix`.
+- ✅ Endurecer `pumuki remove` para podar residuos vacíos de `node_modules` sin borrar dependencias reales de terceros.
+- ✅ Restringir poda de vacíos en `node_modules` a repos sin dependencias externas declaradas (seguridad enterprise reforzada).
+- 🚧 Integrar MCP en `pumuki-mock-consumer` y validar consumo real de `ai_evidence` desde cliente MCP externo.
 
 ## Notas
 - Estrategia obligatoria: commits atómicos por tarea.

package/integrations/lifecycle/consumerPackage.ts

@@ -7,6 +7,8 @@ export type ConsumerDependencySource = 'dependencies' | 'devDependencies' | 'non
 type ConsumerPackageJson = {
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
 };
 
 const readPackageJson = (repoRoot: string): ConsumerPackageJson => {
@@ -46,3 +48,23 @@ export const resolveCurrentPumukiDependency = (repoRoot: string): {
     source: 'none',
   };
 };
+
+export const hasDeclaredDependenciesBeyondPumuki = (repoRoot: string): boolean => {
+  const pkg = readPackageJson(repoRoot);
+  const pumukiPackage = getCurrentPumukiPackageName();
+  const ignoredPackages = new Set([pumukiPackage, 'pumuki-ast-hooks']);
+
+  const hasExternalDependency = (section?: Record<string, string>): boolean => {
+    if (!section) {
+      return false;
+    }
+    return Object.keys(section).some((dependencyName) => !ignoredPackages.has(dependencyName));
+  };
+
+  return (
+    hasExternalDependency(pkg.dependencies) ||
+    hasExternalDependency(pkg.devDependencies) ||
+    hasExternalDependency(pkg.optionalDependencies) ||
+    hasExternalDependency(pkg.peerDependencies)
+  );
+};

package/integrations/lifecycle/remove.ts

@@ -1,6 +1,9 @@
 import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
-import { resolveCurrentPumukiDependency } from './consumerPackage';
+import {
+  hasDeclaredDependenciesBeyondPumuki,
+  resolveCurrentPumukiDependency,
+} from './consumerPackage';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { LifecycleNpmService, type ILifecycleNpmService } from './npmService';
 import { getCurrentPumukiPackageName } from './packageInfo';
@@ -13,12 +16,38 @@ export type LifecycleRemoveResult = {
   removedArtifacts: ReadonlyArray<string>;
 };
 
-const cleanupNodeModulesIfOnlyLockfile = (repoRoot: string): void => {
+const pruneEmptyNodeModulesDirectories = (directoryPath: string): boolean => {
+  const entries = readdirSync(directoryPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const childPath = join(directoryPath, entry.name);
+    const childIsEmpty = pruneEmptyNodeModulesDirectories(childPath);
+    if (childIsEmpty) {
+      rmSync(childPath, { recursive: true, force: true });
+    }
+  }
+
+  return readdirSync(directoryPath).length === 0;
+};
+
+const cleanupNodeModulesIfOnlyLockfile = (
+  repoRoot: string,
+  options?: {
+    allowPruneEmptyDirectories?: boolean;
+  }
+): void => {
   const nodeModulesPath = join(repoRoot, 'node_modules');
   if (!existsSync(nodeModulesPath)) {
     return;
   }
 
+  if (options?.allowPruneEmptyDirectories === true) {
+    pruneEmptyNodeModulesDirectories(nodeModulesPath);
+  }
+
   const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
   if (entries.length === 0) {
     rmSync(nodeModulesPath, { recursive: true, force: true });
@@ -71,10 +100,13 @@ export const runLifecycleRemove = (params?: {
   });
 
   const currentDependency = resolveCurrentPumukiDependency(repoRoot);
+  const hasExternalDependencies = hasDeclaredDependenciesBeyondPumuki(repoRoot);
   const packageName = getCurrentPumukiPackageName();
 
   if (currentDependency.source === 'none') {
-    cleanupNodeModulesIfOnlyLockfile(repoRoot);
+    cleanupNodeModulesIfOnlyLockfile(repoRoot, {
+      allowPruneEmptyDirectories: !hasExternalDependencies,
+    });
     return {
       repoRoot,
       packageRemoved: false,
@@ -84,7 +116,9 @@ export const runLifecycleRemove = (params?: {
   }
 
   npm.runNpm(['uninstall', packageName], repoRoot);
-  cleanupNodeModulesIfOnlyLockfile(repoRoot);
+  cleanupNodeModulesIfOnlyLockfile(repoRoot, {
+    allowPruneEmptyDirectories: !hasExternalDependencies,
+  });
 
   return {
     repoRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.8",
+  "version": "6.3.10",
   "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": {