npm - pumuki - Versions diffs - 6.3.7 → 6.3.9 - Mend

pumuki 6.3.7 → 6.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +143 -256
package/VERSION +1 -1
package/docs/REFRACTOR_PROGRESS.md +5 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -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,193 @@ 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
-```bash
-npm run typecheck
-npm run test:deterministic
-npm run validation:package-manifest
-```
+### 2) Install managed hooks in your repository
-### First run
+Run from the target repository root:
 ```bash
-npm run framework:menu
+npx pumuki install
 ```
-## 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-*`
-Practical rule:
-- normal development: automated pipeline + tests,
-- incident/rollout handling: manual runbook commands.
-## Software Lifecycle
-### Consumer package install (enterprise UX)
+### 3) Verify lifecycle status
 ```bash
-npm install --save-exact pumuki
-npm update pumuki
-npm uninstall pumuki
+npx pumuki doctor
+npx pumuki status
 ```
-`npm upgrade pumuki` is also supported as an alias to update in npm environments where `upgrade` is mapped.
-### Installation (fresh setup)
+### 4) Run stage gates manually (optional)
 ```bash
-npm ci
-npm run typecheck
-npm run test:deterministic
-npm run skills:lock:check
+npx pumuki-pre-commit
+npx pumuki-pre-push
+npx pumuki-ci
 ```
-### Upgrade
+### 5) Expected outputs
-```bash
-git pull
-npm ci
-npm run skills:lock:check
-npm run validation:docs-hygiene
-npm run test:deterministic
-```
+- Gate exit code: `0` (allow) or `1` (block).
+- Deterministic evidence file: `.ai_evidence.json`.
-### Uninstall (local cleanup)
+### Update and remove
 ```bash
-rm -rf node_modules
-rm -rf .audit-reports
+npm update pumuki
+npx pumuki update --latest
+npx --yes pumuki remove
 ```
-If legacy guards are active:
+`pumuki remove` performs managed uninstall + artifact purge in one command.
-```bash
-npm run ast:guard:stop
-```
+## Lifecycle Commands
-For consumer repositories using the package:
+The `pumuki` binary provides repository lifecycle operations:
-```bash
-npx --yes pumuki remove
-```
+| 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 |
-This command also prunes orphan `node_modules/.package-lock.json` residue when no installed modules remain.
+## Gate Commands
-### Dependency conflict troubleshooting
+Dedicated gate binaries are available:
-| 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` |
+| Binary | Stage |
+| --- | --- |
+| `pumuki-pre-commit` | `PRE_COMMIT` |
+| `pumuki-pre-push` | `PRE_PUSH` |
+| `pumuki-ci` | `CI` |
-## Command Reference
+## Architecture and Policy Model
-Flag forwarding pattern:
+### Deterministic pipeline
-```bash
-npm run <script> -- <flags>
-```
+`Facts -> Rules -> Gate -> ai_evidence v2.1`
-### Core, CLI, and framework
+- 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.
-| 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 |
+### Default stage policies
+| 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 CHANGED Viewed

	@@ -1 +1 @@
1	- v6.3.3
1	+ v6.3.9

package/docs/REFRACTOR_PROGRESS.md CHANGED Viewed

@@ -148,6 +148,11 @@ 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.
+- ✅ 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).
 - 🚧 Ejecutar matriz E2E completa en `pumuki-mock-consumer` (`install -> pre-commit/pre-push/ci -> remove`) sobre escenarios `clean`, `violations` y `mixed`.
 ## Notas

package/package.json CHANGED Viewed

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