pumuki 6.3.375 → 6.3.377

package/README.md

@@ -1,390 +1,612 @@
 # Pumuki
 
-<img src="assets/logo.png" alt="Pumuki" width="100%" />
+<p align="center">
+  <img src="assets/logo_banner.png" alt="Pumuki" width="100%" />
+</p>
 
-[![npm version](https://img.shields.io/npm/v/pumuki?color=1d4ed8)](https://www.npmjs.com/package/pumuki)
-[![CI](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
+<p align="center">
+  <a href="https://www.npmjs.com/package/pumuki"><img src="https://img.shields.io/npm/v/pumuki?color=1d4ed8" alt="npm version" /></a>
+  <a href="https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml"><img src="https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/node/v/pumuki" alt="Node.js version" />
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-16a34a" alt="License: MIT" /></a>
+</p>
 
-Enterprise governance framework for AI-assisted software delivery.
+Pumuki is an enterprise governance framework for AI-assisted software delivery.
 
-Pumuki gives engineering teams one deterministic execution model across local development, hooks, and CI:
+It turns repository rules, SDD/OpenSpec workflow, Git hooks, AST intelligence, skills contracts, evidence, notifications, an interactive menu and optional MCP servers into one deterministic delivery contract:
 
-`Facts -> Rules -> Gate -> .ai_evidence.json (v2.1)`
+```text
+Facts -> Rules -> Gate -> Evidence
+```
 
-## Qué NO es Pumuki
+Pumuki is built for teams that need AI agents and humans to follow the same engineering law: know the active change, evaluate the real diff, block unsafe delivery, explain the reason in developer language, and leave auditable evidence.
 
-- **No** es el producto de negocio de tu repositorio (la app, el marketplace, el servicio que entregas a usuarios): es **gobernanza y contrato de entrega** sobre el código.
-- **No** sustituye tests de dominio, contratos de API ni E2E: el gate ayuda a **cumplir políticas y evidencias**; la calidad funcional la define tu equipo con pruebas y criterios de aceptación.
-- **No** garantiza por sí solo “un producto excelente”: sin reglas de equipo, revisión humana y criterios claros, solo obtienes **cumplimiento de lo que configuraste**.
+Current maturity: **advanced beta**. The framework is already useful for governed internal adoption and consumer-repository rollout, but the project is still evolving quickly.
 
-## Who This README Is For
+## Contents
 
-| Profile | Use this path first |
-|---|---|
-| Consumer repository team | [5-Minute Quick Start (Consumer)](#5-minute-quick-start-consumer) |
-| Framework maintainers (this repo) | [Framework Maintainer Flow](#framework-maintainer-flow-this-repo) |
-| Platform/architecture owners | [Enterprise Operations Baseline](#enterprise-operations-baseline) |
+- [Why Pumuki Exists](#why-pumuki-exists)
+- [What Pumuki Does](#what-pumuki-does)
+- [Architecture](#architecture)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Uninstallation and Upgrade](#uninstallation-and-upgrade)
+- [Command Reference](#command-reference)
+- [Git Hooks and CI](#git-hooks-and-ci)
+- [SDD and OpenSpec](#sdd-and-openspec)
+- [Session Continuity and AI Window Handoff](#session-continuity-and-ai-window-handoff)
+- [AST Intelligence and Rule Packs](#ast-intelligence-and-rule-packs)
+- [Evidence](#evidence)
+- [Menu and Notifications](#menu-and-notifications)
+- [MCP and Agent Adapters](#mcp-and-agent-adapters)
+- [Enterprise Operations](#enterprise-operations)
+- [Adoption Models](#adoption-models)
+- [Troubleshooting](#troubleshooting)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
 
-## Rutas de adopción
+## Why Pumuki Exists
 
-Elige un perfil y profundiza en los enlaces; **no** repite aquí reglas largas (skills, GitFlow, políticas) — están en `AGENTS.md` y en la documentación enlazada.
+AI-assisted development increases delivery speed, but it also increases the risk of ungoverned changes: skipped tests, missing specs, vague evidence, mixed commits, stale repo context, unsafe hooks, and rules that live only in documentation.
 
-| Perfil | Qué instalar / arrancar | Stages habituales | Opcional típico |
-|--------|-------------------------|-------------------|-----------------|
-| **Mínimo** | `npm install --save-exact pumuki` (en repos Git el `postinstall` ejecuta baseline `pumuki install`; `--with-mcp --agent=repo` es opt-in con `PUMUKI_POSTINSTALL_WITH_MCP=1` o `PUMUKI_POSTINSTALL_MCP_AGENT=repo`). | Hooks Git: **PRE_COMMIT**, **PRE_PUSH**; cadena **PRE_WRITE** cuando el hook lo encadena (según versión y config). | Evidencia [`.ai_evidence.json` v2.1](docs/mcp/ai-evidence-v2.1-contract.md); reglas core embebidas. |
-| **Estándar** | Lo anterior + flujo **OpenSpec/SDD** bajo `openspec/` según tu política. | Lo anterior + validación SDD por stage (`pumuki sdd validate --stage=…`). | Sesiones SDD, cambios versionados bajo `openspec/changes/`. |
-| **Enterprise completo** | `pumuki bootstrap --enterprise` (o equivalente documentado) + `skills.lock.json` / reglas custom / [policy-as-code](docs/product/CONFIGURATION.md) donde aplique. | Lo anterior + **CI** (`pumuki-ci`) y comprobaciones de alineación (`doctor`, parity). | [Skills / MCP](docs/mcp/mcp-servers-overview.md), `pumuki doctor --parity`, notificaciones, [hard mode](docs/product/CONFIGURATION.md). |
+Pumuki makes those rules executable.
 
-Referencias canónicas (profundizar aquí): [Instalación](docs/product/INSTALLATION.md), [Uso y gates](docs/product/USAGE.md), [Configuración](docs/product/CONFIGURATION.md), [AGENTS.md](AGENTS.md) (contrato agentes/skills/GitFlow en repos que lo adopten), [índice de documentación](docs/README.md).
+It is designed to answer operational questions before a change enters the repository:
 
-Formación opcional (curso **Pumuki** dentro del hub *Stack My Architecture*): [https://stack-my-architecture-hub.vercel.app/pumuki/](https://stack-my-architecture-hub.vercel.app/pumuki/) · seguimiento de la iniciativa en [docs/tracking/plan-curso-pumuki-stack-my-architecture.md](docs/tracking/plan-curso-pumuki-stack-my-architecture.md).
+| Question | Pumuki answer |
+|---|---|
+| What is being changed? | Git scope, SDD context and repository facts. |
+| Which rules apply? | Platform rule packs, skills contracts, policy-as-code and project overrides. |
+| Can this change proceed? | Deterministic gate decision per stage. |
+| Why was it blocked? | Developer-facing cause, file, rule and remediation. |
+| What evidence remains? | `.ai_evidence.json` v2.1 plus optional MCP/telemetry access. |
 
-## Comandos esenciales
+Pumuki does not replace product tests, code review, domain acceptance criteria or security review. It enforces the delivery contract around them.
 
-Cinco entradas que cubren el 80 % del día a día en un consumidor; el detalle está en los enlaces.
+## What Pumuki Does
 
-1. **`npx pumuki doctor --json`** — Versión efectiva, drift, lifecycle, parity y avisos (p. ej. `pathExecutionHazard`). Detalle: [API_REFERENCE](docs/product/API_REFERENCE.md), [USAGE](docs/product/USAGE.md).
-2. **`npx pumuki status --json`** — Estado resumido del menú/lifecycle y alineación de versión. Detalle: [USAGE](docs/product/USAGE.md).
-3. **`npx pumuki install`** (o deja que el `postinstall` lo ejecute en Git) — Hooks y lifecycle en el repo. Detalle: [INSTALLATION](docs/product/INSTALLATION.md).
-4. **Gates locales** — `npx pumuki-pre-write`, `npx pumuki-pre-commit` (y `pumuki-pre-push` cuando toque push). Detalle: [USAGE](docs/product/USAGE.md), [Troubleshooting (USAGE)](docs/product/USAGE.md#troubleshooting).
-5. **SDD por stage (enterprise)** — `npx pumuki sdd validate --stage=PRE_COMMIT` (u otro stage). Detalle: [USAGE](docs/product/USAGE.md), [INSTALLATION](docs/product/INSTALLATION.md#troubleshooting) si falla el bootstrap.
+Pumuki provides a governed delivery surface for modern repositories:
 
-**Desarrollo en este repo (sin depender de GitHub Actions):** barra mínima antes de merge o publicar — `npm run -s validation:local-merge-bar` (`typecheck` + smoke de superficie CLI + `npm test`). Detalle del smoke: [docs/validation/README.md](docs/validation/README.md).
+| Capability | What it provides |
+|---|---|
+| Git lifecycle | Managed `pre-commit` and `pre-push` hooks, with chained `PRE_WRITE` by default. |
+| Stage gates | `PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH` and `CI` policies with deterministic semantics. |
+| Full audit | `pumuki audit` for tracked-repository evaluation outside a hook. |
+| SDD/OpenSpec | Change sessions, validation, evidence sync and state sync. |
+| Session continuity | Repo-owned context, SDD state, evidence and MCP resources so a new AI window can resume from facts instead of chat memory. |
+| AST intelligence | Rule-backed findings for iOS, Android, backend, frontend and generic TypeScript patterns. |
+| Skills contracts | Compiled rules from enterprise skills, with coverage checks and missing-detector protection. |
+| Evidence | Stable `.ai_evidence.json` v2.1 snapshots for auditability and automation. |
+| Developer UX | Interactive menu, clear blocking messages, terminal output and system notifications. |
+| MCP | Optional evidence and enterprise MCP servers over HTTP or stdio. |
+| Adapters | Provider-agnostic adapter scaffolding for Codex, Claude, Cursor, Windsurf and Opencode. |
+| Policy-as-code | Optional signed stage-policy contract under `.pumuki/policy-as-code.json`. |
+| Telemetry | Optional JSONL and OTLP export for enterprise observability. |
+| Brownfield control | Scope-aware gates that avoid blocking a slice for unrelated historical debt. |
+
+## Architecture
+
+<p align="center">
+  <img src="assets/readme/pumuki-governance-flow.svg" alt="Pumuki governance flow" width="100%" />
+</p>
+
+Pumuki keeps product decisions deterministic by separating domain logic from integrations:
+
+| Layer | Responsibility |
+|---|---|
+| `core/*` | Facts, rules, rule presets and gate decision model. |
+| `integrations/*` | Git scopes, stage policies, evidence, SDD, MCP, notifications and lifecycle adapters. |
+| `bin/*` | Public CLI binaries published by npm. |
+| `docs/*` | Product documentation, operation guides, MCP contracts and rule-pack references. |
+| `vendor/skills/*` | Vendored enterprise skill contracts consumed by the rules compiler. |
+
+Core pipeline:
+
+```text
+Git scope / repo state
+  -> fact extraction
+  -> platform detection
+  -> rule-pack and skills loading
+  -> stage policy evaluation
+  -> gate decision
+  -> evidence, notification and optional MCP/telemetry output
+```
 
-Si algo bloquea o el mensaje no es claro: [Troubleshooting](#troubleshooting) (más abajo en este README), [USAGE § Troubleshooting](docs/product/USAGE.md#troubleshooting) y [GitHub Issues](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues).
+Pumuki is IDE-agnostic at baseline. Git hooks, gates, lifecycle, evidence and policy enforcement do not require Cursor, Codex, Claude or any other IDE. IDE/client files are opt-in adapter output.
 
-## 5-Minute Quick Start (Consumer)
+## Quick Start
 
 Prerequisites:
 
-- Node.js `>= 18`
-- npm `>= 9`
+- Node.js `>=18`
+- npm `>=9`
 - Git repository
 
-Install and bootstrap:
+Install Pumuki in a consumer repository:
 
 ```bash
 npm install --save-exact pumuki
-npx --yes pumuki bootstrap --enterprise --agent=codex
-npx --yes pumuki status
-npx --yes pumuki doctor --json
+npx --yes pumuki bootstrap --enterprise
+npx --yes pumuki status --json
+npx --yes pumuki doctor --deep --json
 ```
 
-Desde **6.3.63**, `npm install` en la raíz de un repo **Git** dispara un `postinstall` que ejecuta baseline **`pumuki install`** (hooks `pre-commit` / `pre-push`, lifecycle, merge de **`.pumuki/adapter.json`** con comandos MCP stdio, sin rutas de IDE salvo opt-in). El wiring MCP no va activado por defecto; para activarlo en postinstall usa `PUMUKI_POSTINSTALL_WITH_MCP=1` o `PUMUKI_POSTINSTALL_MCP_AGENT=repo/cursor/claude/codex`. **Pumuki no depende de ningún IDE** para el baseline. Opt-out del postinstall: `PUMUKI_SKIP_POSTINSTALL=1`. Ficheros de IDE en postinstall: `PUMUKI_POSTINSTALL_MCP_AGENT=cursor|claude|codex` o comando manual / `bootstrap`. Desde **6.3.68**, cada hook gestionado ejecuta **`pumuki-pre-write` antes** de `pumuki-pre-commit` / `pumuki-pre-push` (stage **PRE_WRITE** vía Git). Saltar solo PRE_WRITE en hooks: `PUMUKI_SKIP_CHAINED_PRE_WRITE=1`. Desde **6.3.69**, esos mismos hooks aplican también **git-flow en ramas protegidas** (`GITFLOW_PROTECTED_BRANCH`) e **higiene de worktree** (`PUMUKI_PREWRITE_WORKTREE_*` / códigos `EVIDENCE_PREWRITE_WORKTREE_*`) cuando la evidencia es válida; el **modal macOS** de bloqueo (Desactivar / Silenciar 30 min / Mantener activas) queda **activo por defecto** si las notificaciones están habilitadas (`"blockedDialogEnabled": false` o `PUMUKI_MACOS_BLOCKED_DIALOG=0` para apagarlo). Desactivar el postinstall: `PUMUKI_SKIP_POSTINSTALL=1`. En CI suele saltarse solo (`CI=true`). En **6.3.64+**, las notificaciones del sistema en plataformas sin banner nativo se reflejan en **stderr** por defecto (`PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` para silenciarlas). En **6.3.69+**, un `gate.blocked` en macOS también deja una copia en **stderr** por defecto (`PUMUKI_DISABLE_GATE_BLOCKED_STDERR_MIRROR=1` para desactivar solo eso). Desde **6.3.70**, si **`.ai_evidence.json` está versionado** y **PRE_PUSH** no bloquea, ese archivo **no se reescribe** en el push (compatibilidad con **pre-commit** como hook de **pre-push**); para forzar escritura: `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1`. Con modal de bloqueo activo, el panel interactivo prioriza foco/clics y se evita el banner duplicado.
-
-Fallback (equivalent in pasos separados):
+After bootstrap, the normal developer path is intentionally small:
 
 ```bash
-npx --yes pumuki install --with-mcp --agent=codex
-npx --yes pumuki doctor --deep --json
+git add <files>
+git commit
+git push
 ```
 
-OpenSpec/SDD baseline:
+Managed hooks run the required Pumuki lifecycle automatically. Teams only reach for explicit commands when they need setup, diagnostics, CI wiring, SDD evidence, MCP servers or operational recovery.
+
+Open a governed SDD change session when the repository requires explicit SDD/OpenSpec control:
 
 ```bash
 npx --yes pumuki sdd status
-mkdir -p openspec/changes/<change-id>
 npx --yes pumuki sdd session --open --change=<change-id>
-npx --yes pumuki sdd validate --stage=PRE_COMMIT
+npx --yes pumuki sdd validate --stage=PRE_COMMIT --json
 ```
 
-Optional loop runner session (local, deterministic):
+Run a full tracked-repository audit only for diagnostics or governance reporting:
 
 ```bash
-npx --yes pumuki loop run --objective="stabilize gate before commit" --max-attempts=3 --json
-npx --yes pumuki loop list --json
+npx --yes pumuki audit --json
+npx --yes pumuki audit --stage=CI --engine --json
 ```
 
-Run local gates:
+## Installation
+
+### Consumer Repository
+
+Recommended enterprise path:
 
 ```bash
-npx --yes --package pumuki@latest pumuki-pre-write
-npx --yes --package pumuki@latest pumuki-pre-commit
+npm install --save-exact pumuki
+npx --yes pumuki bootstrap --enterprise
 ```
 
-Run push/CI gates (requires proper git context):
+What the bootstrap path does:
+
+- installs managed Git hooks;
+- configures lifecycle state;
+- creates `.pumuki/adapter.json` when missing;
+- prepares OpenSpec/SDD baseline where applicable;
+- initializes evidence when missing;
+- runs deep diagnostics.
+
+The package `postinstall` runs a baseline `pumuki install` in Git repositories unless disabled. That baseline is IDE-agnostic: hooks, lifecycle and `.pumuki/adapter.json` are the default product surface.
+
+Useful postinstall controls:
+
+| Variable | Effect |
+|---|---|
+| `PUMUKI_SKIP_POSTINSTALL=1` | Disable postinstall bootstrap. |
+| `PUMUKI_POSTINSTALL_WITH_MCP=1` | Include MCP wiring during postinstall. |
+| `PUMUKI_POSTINSTALL_MCP_AGENT=<agent>` | Select optional adapter/client wiring for postinstall. |
+| `PUMUKI_SKIP_CHAINED_PRE_WRITE=1` | Skip chained `PRE_WRITE` inside managed hooks. |
+
+### Framework Repository
+
+For maintainers of this repository:
 
 ```bash
-git push --set-upstream origin <branch>
-npx --yes --package pumuki@latest pumuki-pre-push
-npx --yes --package pumuki@latest pumuki-ci
+git clone https://github.com/SwiftEnProfundidad/ast-intelligence-hooks.git
+cd ast-intelligence-hooks
+npm ci
+npm run -s typecheck
+npm run -s test:deterministic
 ```
 
-Expected behavior:
+## Uninstallation and Upgrade
 
-- `PRE_WRITE` and `PRE_COMMIT`: should pass when SDD session is valid and rules are satisfied.
-- `PRE_PUSH`: blocks if branch has no upstream tracking reference.
-- `CI`: requires a valid diff range context (not `HEAD..HEAD` with ambiguous range).
+Plain npm removal only removes the dependency. It does not remove managed lifecycle state.
 
-Version drift quick check:
+| Goal | Command |
+|---|---|
+| Remove managed hooks and purge runtime artifacts | `npx --yes pumuki uninstall --purge-artifacts` |
+| Remove lifecycle and dependency from package manifests | `npx --yes pumuki remove` |
+| Update to latest package and reapply hooks | `npx --yes pumuki update --latest` |
+| Standard npm dependency removal only | `npm uninstall pumuki` |
 
-- `status --json` and `doctor --json` expose `version.effective`, `version.runtime`, `version.consumerInstalled`, `version.lifecycleInstalled`, `version.driftWarning`, `version.alignmentCommand`, `version.pathExecutionHazard`, `version.pathExecutionWarning`, and `version.pathExecutionWorkaroundCommand`.
-- If `driftWarning` is not `null`, prefer the exact command already exposed in `version.alignmentCommand`.
-- If `pathExecutionHazard` is `true`, avoid `npx/npm exec` for the install step and use the safe local workaround reported by Pumuki, for example:
+Recommended upgrade check:
 
 ```bash
-node ./node_modules/pumuki/bin/pumuki.js install
+npm install --save-exact pumuki@latest
+npx --yes pumuki status --json
+npx --yes pumuki doctor --deep --json
+npx --yes pumuki policy reconcile --strict --json
 ```
 
-## Why Pumuki
+If `status` or `doctor` reports version drift, use the `alignmentCommand` printed in the JSON payload.
+
+## Command Reference
+
+The main lifecycle binary is `pumuki`. This section is an operator reference, not the expected daily developer workflow. The intended enterprise path is progressive disclosure:
+
+1. `bootstrap` once per repository.
+2. work through normal Git operations.
+3. let managed hooks, CI and policy decide automatically.
+4. use explicit commands only for diagnostics, evidence, adapters, SDD operations or automation.
+
+```text
+pumuki --version | -v
+pumuki bootstrap [--enterprise] [--agent=<name>] [--json]
+pumuki install [--with-mcp] [--agent=<name>]
+pumuki uninstall [--purge-artifacts]
+pumuki remove
+pumuki update [--latest|--spec=<package-spec>]
+pumuki doctor [--remote-checks] [--deep] [--parity] [--json]
+pumuki audit [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--engine] [--json]
+pumuki status [--json] [--remote-checks]
+pumuki menu
+pumuki watch [--stage=<stage>] [--scope=<scope>] [--once] [--json]
+pumuki loop run --objective=<text> [--max-attempts=<n>] [--json]
+pumuki adapter install --agent=<name> [--dry-run] [--json]
+pumuki analytics hotspots report [--top=<n>] [--since-days=<n>] [--json]
+pumuki analytics hotspots diagnose [--json]
+pumuki policy reconcile [--strict] [--apply] [--json]
+pumuki context init|status|repair [--json]
+pumuki sdd status|validate|session|sync-docs|sync|learn|auto-sync|evidence|state-sync
+```
 
-Modern teams need fast feedback with strict governance. Pumuki combines:
+Published binaries:
 
-- Deterministic enforcement per stage (`PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, `CI`).
-- A single evidence contract (`.ai_evidence.json`, v2.1) for auditability and automation.
-- Multi-platform governance (iOS, Android, Backend, Frontend).
-- Unified skills engine with deterministic precedence (`core -> repo -> custom`).
-- Mandatory OpenSpec/SDD checks for enterprise change control.
-- Unified CLI plus optional MCP servers for agent-driven workflows.
+| Binary | Purpose |
+|---|---|
+| `pumuki` | Main lifecycle CLI. |
+| `pumuki-framework`, `pumuki-ast-hooks`, `ast-hooks` | Interactive framework/menu entrypoints. |
+| `pumuki-pre-write` | PRE_WRITE gate and SDD policy surface. |
+| `pumuki-pre-commit` | PRE_COMMIT hook runner. |
+| `pumuki-pre-push` | PRE_PUSH hook runner. |
+| `pumuki-ci` | CI gate runner. |
+| `pumuki-mcp-evidence` | Evidence MCP HTTP server. |
+| `pumuki-mcp-enterprise` | Enterprise MCP HTTP server. |
+| `pumuki-mcp-evidence-stdio` | Evidence MCP stdio bridge. |
+| `pumuki-mcp-enterprise-stdio` | Enterprise MCP stdio bridge. |
 
-## Enterprise Execution Model
+Detailed command documentation:
 
-Each execution follows the same pipeline:
+- [Installation Guide](docs/product/INSTALLATION.md)
+- [Usage Guide](docs/product/USAGE.md)
+- [API Reference](docs/product/API_REFERENCE.md)
+- [Operator Playbook](PUMUKI.md)
 
-1. Facts extraction from staged/range/repo scope.
-2. Rule evaluation by platform and stage policy.
-3. Gate decision (`PASS`, `WARN`, `BLOCK`) with deterministic thresholds.
-4. Evidence emission (`.ai_evidence.json`) with findings, metadata, and coverage telemetry.
+## Git Hooks and CI
 
-Rules resolution order:
+Pumuki evaluates different scopes per stage:
 
-1. Core rules (embedded package snapshot).
-2. Repo rules (`skills.lock.json`), optional.
-3. Custom rules (`.pumuki/custom-rules.json`), optional.
+| Stage | Typical trigger | Scope | Purpose |
+|---|---|---|---|
+| `PRE_WRITE` | Before hook execution or explicit guard | Active write/session context | Prevent unmanaged agent work and invalid SDD state. |
+| `PRE_COMMIT` | `pre-commit` | `git diff --cached` | Protect the atomic commit. |
+| `PRE_PUSH` | `pre-push` | `upstream..HEAD` | Protect outgoing branch range. |
+| `CI` | CI job | CI base range | Repeat the same governance outside the laptop. |
+| `audit` | Manual CLI | Git tracked files | Diagnose the full tracked repository. |
 
-Conflict policy:
+Managed `pre-commit` and `pre-push` hooks run `pumuki-pre-write` first by default, then the stage runner. Use `PUMUKI_SKIP_CHAINED_PRE_WRITE=1` only for explicit operational exceptions.
 
-- `custom > repo > core` (last writer wins by `ruleId`).
-- Platform rules activate only for detected platforms.
-- `generic/text` rules remain available as cross-platform governance guards.
+CI entrypoint:
 
-Rule modes:
+```bash
+npx --yes --package pumuki@latest pumuki-ci
+```
 
-- `AUTO`: mapped to deterministic detectors/heuristics.
-- `DECLARATIVE`: valid only when explicitly declared in lock/custom payload (no silent fallback for rules extracted from skills markdown).
+When GitHub Actions quota or remote CI is not available, this repository uses local validation as the operational merge bar:
 
-## Core Capabilities
+```bash
+npm run -s validation:local-merge-bar
+```
 
-1. Deterministic stage gates with consistent exit semantics.
-2. Evidence v2.1 with rules coverage enforcement and stable ordering.
-3. Unified skills rules engine (core + repo + custom).
-4. Unified AI gate behavior across CLI and MCP surfaces.
-5. Mandatory OpenSpec/SDD policy checks.
-6. Interactive menu UX (consumer + advanced modes).
-7. Hard mode policy hardening (`.pumuki/hard-mode.json` + env overrides).
-8. Lifecycle commands for install/update/diagnostics/teardown.
-9. Provider-agnostic adapter scaffolding (`codex`, `claude`, `cursor`, `windsurf`, `opencode`).
-10. Optional MCP servers for evidence and enterprise context.
+## SDD and OpenSpec
 
-## Policy-as-Code (Enterprise)
+Pumuki supports a mandatory SDD/OpenSpec delivery workflow for enterprise repositories.
 
-Pumuki supports a signed and versioned stage-policy contract at:
+Common commands:
 
-- `.pumuki/policy-as-code.json`
+```bash
+npx --yes pumuki sdd status --json
+npx --yes pumuki sdd session --open --change=<change-id> --json
+npx --yes pumuki sdd session --refresh --ttl-minutes=90 --json
+npx --yes pumuki sdd validate --stage=PRE_WRITE --json
+npx --yes pumuki sdd evidence --scenario-id=<id> --test-command='<command>' --test-status=passed --json
+npx --yes pumuki sdd state-sync --scenario-id=<id> --status=done --dry-run --json
+```
+
+Stage aliases:
+
+| Alias | Stage |
+|---|---|
+| `RED` | `PRE_WRITE` |
+| `GREEN` | `PRE_COMMIT` |
+| `REFACTOR` | `PRE_PUSH` |
+| `CLOSE` | `CI` |
 
-Minimal contract:
+OpenSpec is resolved from the checked repository, not from a random global binary on `PATH`. Install or bootstrap Pumuki inside the repository so local and CI behavior match.
 
-```json
-{
-  "version": "1.0",
-  "source": "default",
-  "expires_at": "2026-12-31T23:59:59.000Z",
-  "signatures": {
-    "PRE_COMMIT": "<sha256-hex>",
-    "PRE_PUSH": "<sha256-hex>",
-    "CI": "<sha256-hex>"
-  }
-}
+## Session Continuity and AI Window Handoff
+
+Pumuki is designed for AI-assisted work where the chat window, IDE session or CLI agent can change before the repository work is finished.
+
+It does not claim to preserve private conversational memory from a vendor window. Instead, it externalizes the operational context that matters into repository-owned, auditable state:
+
+| Context surface | What it preserves |
+|---|---|
+| `.pumuki/context/context.json` | Local context contract for the repository and the instruction that an AI agent must stop if the context cannot be read or validated. |
+| `pumuki context init|status|repair` | Initialize, validate or repair the local context gate before edits, audits, commits or pushes. |
+| SDD/OpenSpec session state | Active change id, session validity and stage validation through `pumuki sdd status`, `session` and `validate`. |
+| `.ai_evidence.json` v2.1 | Last gate snapshot, findings, platform detection, rule provenance, severity breakdown and operational hints. |
+| Managed hooks and receipts | PRE_WRITE/PRE_COMMIT/PRE_PUSH/CI decisions, MCP receipt freshness and evidence age. |
+| MCP resources | Provider-agnostic resources such as `context://active`, `sdd://status`, `sdd://active-change`, `gitflow://state` and `evidence://status`. |
+
+This makes a new AI window resumable from facts:
+
+```bash
+npx --yes pumuki status --json
+npx --yes pumuki context status --json
+npx --yes pumuki sdd status --json
+npx --yes pumuki doctor --deep --json
 ```
 
-Runtime behavior:
+For MCP-capable clients, the same pattern is available through read-only context resources and evidence endpoints before an agent edits files. The expected agent behavior is conservative: if context, evidence or SDD state is missing or invalid, the agent should downgrade to diagnosis and report a blocker instead of mutating production code.
+
+In practice, Pumuki turns "remember what we were doing" into a repository contract: current branch, lifecycle health, active SDD change, latest evidence, blocking findings, remediation and policy provenance are recoverable without trusting the transient memory of one AI session.
 
-- If the contract is missing, Pumuki computes deterministic local metadata and still emits `policy_version`, `policy_signature`, and `policy_source`.
-- If present, the contract is validated against active runtime policy for source/stage/signature.
-- Validation states are emitted as `valid`, `invalid`, `expired`, or `unknown-source`.
-- `PUMUKI_POLICY_STRICT=1` turns non-valid states into blocking findings (`governance.policy-as-code.invalid`).
+## AST Intelligence and Rule Packs
 
-Operational fallback:
+Pumuki detects active platforms and loads rule packs for the real repository shape:
 
-- Keep strict mode disabled while bootstrapping a repo without a canonical contract.
-- Enable strict mode once contract generation/signatures are part of your baseline pipeline.
+| Platform | Coverage area |
+|---|---|
+| iOS | Swift, SwiftUI, Swift Testing, concurrency, architecture and security patterns. |
+| Android | Kotlin, Compose, DI, lifecycle, architecture and Android-specific risk patterns. |
+| Backend | TypeScript/NestJS, DTO validation, controllers, DI, error handling, persistence and security patterns. |
+| Frontend | TypeScript/React/Next.js, JSX accessibility, API routes, UI safety and browser risk patterns. |
+| Generic | Cross-platform TypeScript, process, filesystem, dynamic code execution and security signals. |
 
-## Telemetry Export (Enterprise)
+Current baseline families:
 
-Pumuki can export structured gate telemetry with a stable event schema (`telemetry_event_v1`) for SIEM/observability pipelines.
+- `iosEnterpriseRuleSet`
+- `backendRuleSet`
+- `frontendRuleSet`
+- `androidRuleSet`
+- `astHeuristicsRuleSet`
+- compiled skills bundles from `skills.lock.json`
 
-Default behavior remains unchanged: telemetry export is disabled unless explicitly configured.
+Rule-pack documentation:
 
-Enable one or both outputs:
+- [Rule Packs Overview](docs/rule-packs/README.md)
+- [iOS Rule Pack](docs/rule-packs/ios.md)
+- [Android Rule Pack](docs/rule-packs/android.md)
+- [Backend Rule Pack](docs/rule-packs/backend.md)
+- [Frontend Rule Pack](docs/rule-packs/frontend.md)
+- [AST Heuristics Rule Pack](docs/rule-packs/heuristics.md)
 
-- `PUMUKI_TELEMETRY_JSONL_PATH`: local JSONL target (absolute or repo-relative path)
-- `PUMUKI_TELEMETRY_OTEL_ENDPOINT`: OTLP HTTP logs endpoint (`/v1/logs`)
-- `PUMUKI_TELEMETRY_OTEL_SERVICE_NAME`: optional OTel service name (default: `pumuki`)
-- `PUMUKI_TELEMETRY_OTEL_TIMEOUT_MS`: optional OTel timeout in ms (default: `1500`)
+AST intelligence is not a promise that every guideline can be enforced as code. Pumuki distinguishes runtime-code rules, process rules, positive recommendations and rules that still require study, so the gate does not create false confidence.
 
-Example:
+## Evidence
 
-```bash
-export PUMUKI_TELEMETRY_JSONL_PATH=".pumuki/artifacts/gate-telemetry.jsonl"
-export PUMUKI_TELEMETRY_OTEL_ENDPOINT="https://otel.example/v1/logs"
-export PUMUKI_TELEMETRY_OTEL_SERVICE_NAME="pumuki-enterprise"
-npx --yes --package pumuki@latest pumuki-pre-commit
-```
+Pumuki writes deterministic evidence to `.ai_evidence.json` using the v2.1 contract.
+
+Evidence can include:
+
+- stage and policy metadata;
+- gate outcome;
+- findings and blocking causes;
+- loaded rulesets and content hashes;
+- detected platforms;
+- skills coverage;
+- SDD/OpenSpec state;
+- operational hints;
+- ledger and snapshot metadata.
 
-Each event captures deterministic stage/outcome/policy/repo context per gate execution.
+Reference:
 
-## Framework Maintainer Flow (This Repo)
+- [AI Evidence v2.1 Contract](docs/mcp/ai-evidence-v2.1-contract.md)
+- [Evidence API](docs/product/API_REFERENCE.md#evidence-api)
 
-Use this only when working in the Pumuki framework repository itself:
+## Menu and Notifications
+
+Pumuki includes an interactive menu for local developer operation.
+
+Framework repository:
 
 ```bash
 npm run framework:menu
-PUMUKI_MENU_UI_V2=1 npm run framework:menu
 PUMUKI_MENU_MODE=advanced npm run framework:menu
 ```
 
-Skills engine operations:
+Consumer repository:
 
 ```bash
-npm run skills:compile
-npm run skills:lock:check
-npm run skills:import:custom
-npm run skills:import:custom -- --source <absolute-path-to-SKILL.md> --source <second-absolute-path-to-SKILL.md>
+npx --yes --package pumuki@latest pumuki-framework
 ```
 
-Adapter scaffolding:
+Screenshots from the consumer menu:
 
-```bash
-npx --yes pumuki adapter install --agent=codex --dry-run
-npx --yes pumuki adapter install --agent=cursor
-npm run adapter:install -- --agent=claude
-```
+| Consumer menu | Blocked pre-flight | Final summary |
+|---|---|---|
+| ![Consumer menu](assets/readme/menu-option1/01-menu-consumer-v2.png) | ![Pre-flight block](assets/readme/menu-option1/02-option1-preflight-block.png) | ![Final block](assets/readme/menu-option1/03-option1-final-summary-block.png) |
+
+Notification channels include terminal output, stderr mirrors for relevant blocking events and optional system notifications. Blocking messages are expected to explain:
+
+1. blocking cause;
+2. concrete rule or skill;
+3. file and line when available;
+4. missing condition;
+5. direct remediation.
+
+Extended walkthrough:
+
+- [Framework Menu Consumer Walkthrough](docs/operations/framework-menu-consumer-walkthrough.md)
 
-Operational matrix/canary:
+## MCP and Agent Adapters
+
+MCP is optional. Git hooks and gates do not depend on MCP.
+
+Pumuki publishes two MCP server families:
+
+| Server | Purpose |
+|---|---|
+| `pumuki-mcp-evidence` | Read-only evidence context over HTTP. |
+| `pumuki-mcp-enterprise` | Enterprise repository state, resources and safe tools over HTTP. |
+| `pumuki-mcp-evidence-stdio` | Evidence resources over MCP stdio. |
+| `pumuki-mcp-enterprise-stdio` | Enterprise resources/tools over MCP stdio. |
+
+The enterprise server exposes repository-state resources used for session continuity, including `context://active`, `gitflow://state`, `sdd://status`, `sdd://active-change` and `evidence://status`. The evidence server exposes compact and paginated evidence views so agents can load only the facts they need before acting.
+
+Consumer quick start:
 
 ```bash
-node --import tsx -e "const mod = await import('./scripts/framework-menu-matrix-runner-lib.ts'); const report = await mod.default.runConsumerMenuMatrix({ repoRoot: process.cwd() }); console.log(JSON.stringify(report, null, 2));"
-node --import tsx -e "const mod = await import('./scripts/framework-menu-matrix-canary-lib.ts'); const report = await mod.default.runConsumerMenuCanary({ repoRoot: process.cwd() }); console.log(JSON.stringify(report, null, 2));"
+npx --yes --package pumuki@latest pumuki-mcp-evidence
+npx --yes --package pumuki@latest pumuki-mcp-enterprise
+npx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio
 ```
 
-Legacy parity report (strict comparator):
+Adapter scaffolding:
 
 ```bash
-node --import tsx scripts/build-legacy-parity-report.ts --legacy=<legacy-evidence-path> --enterprise=<enterprise-evidence-path> --out=<output-path>
+npx --yes pumuki adapter install --agent=repo --dry-run --json
+npx --yes pumuki adapter install --agent=<agent> --json
+npx --yes pumuki adapter install --agent=cursor --dry-run --json
 ```
 
-## Command Paths
+Supported adapter targets include `repo`, `cursor`, `claude`, `codex`, `windsurf` and `opencode`. These are opt-in client adapters; the managed Git hooks, gates, lifecycle, evidence and `.pumuki/adapter.json` baseline remain AI-agent, CLI and IDE agnostic.
 
-Use these docs instead of treating `README.md` as the full command manual:
+References:
 
-- Installation and bootstrap:
-  - `docs/product/INSTALLATION.md`
-- Daily usage, gates, menu, lifecycle, SDD and troubleshooting:
-  - `docs/product/USAGE.md`
-- Operator-focused short playbook:
-  - `PUMUKI.md`
-- Validation runbooks and framework-only diagnostics:
-  - `docs/validation/README.md`
+- [MCP Servers](docs/mcp/mcp-servers-overview.md)
+- [Evidence Context Server](docs/mcp/evidence-context-server.md)
+- [Agent Context Consumption](docs/mcp/agent-context-consumption.md)
 
-## Menu Walkthrough and Screenshots
+## Enterprise Operations
 
-### Capture 1 — Consumer Menu (v2)
+Pumuki includes enterprise-oriented controls for teams that need governed rollout across multiple repositories.
 
-![Consumer Menu v2](assets/readme/menu-option1/01-menu-consumer-v2.png)
+| Area | Capability |
+|---|---|
+| Policy-as-code | `.pumuki/policy-as-code.json` with stage signatures and strict validation. |
+| Telemetry | Optional JSONL and OTLP export for gate telemetry. |
+| Version drift | `status` and `doctor` expose effective/runtime/lifecycle/package alignment. |
+| Adapter health | Deep diagnostics for hook and MCP wiring. |
+| Worktree hygiene | Guardrails for pending changes and atomic delivery. |
+| Consumer rollout | Package smoke, installed-bin smoke and consumer support tooling. |
+| Operations policy | SLO/SLA, severity model, incident response and rollback expectations. |
 
-### Capture 2 — Option 1 Pre-flight (BLOCK context)
+Operational references:
 
-![Option 1 Pre-flight Block](assets/readme/menu-option1/02-option1-preflight-block.png)
+- [Configuration](docs/product/CONFIGURATION.md)
+- [Production Operations Policy](docs/operations/production-operations-policy.md)
+- [Validation Runbooks](docs/validation/README.md)
+- [Release Notes](docs/operations/RELEASE_NOTES.md)
+- [Changelog](CHANGELOG.md)
 
-### Capture 3 — Option 1 Final Summary (BLOCK)
+## Adoption Models
 
-![Option 1 Final Summary Block](assets/readme/menu-option1/03-option1-final-summary-block.png)
+| Context | Recommended path |
+|---|---|
+| Greenfield repository | Install Pumuki early, enable SDD/OpenSpec, commit through hooks from day one. |
+| Brownfield repository | Start with scoped hooks and audits; fix active-slice debt before historical debt. |
+| AI-enabled team | Treat `AGENTS.md` and skills as the human contract, and Pumuki as executable enforcement. |
+| Multi-platform monorepo | Pin platforms when needed and let rule packs activate by detected scope. |
+| Enterprise rollout | Pilot in one consumer, validate `doctor/status/hooks`, then repin controlled repositories. |
+
+Suggested rollout checklist:
+
+1. Install exact package version.
+2. Run `pumuki bootstrap --enterprise`.
+3. Verify `status` and `doctor`.
+4. Open an SDD session for a real change.
+5. Run `PRE_WRITE` and `PRE_COMMIT`.
+6. Validate menu and notification output.
+7. Add CI gate when the local contract is stable.
+8. Document local exceptions in the consumer repository.
 
-### Capture 4 — Option 1 Pre-flight (PASS scenario)
+## Troubleshooting
 
-![Option 1 Pre-flight Pass Scenario](assets/readme/menu-option1/04-option1-preflight-pass.png)
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `SDD_SESSION_MISSING` | No active SDD session. | Run `pumuki sdd session --open --change=<change-id>`. |
+| `SDD_SESSION_INVALID` | Session does not match current change or expired. | Run `pumuki sdd session --refresh --ttl-minutes=90`. |
+| `OPENSPEC_MISSING` | Repo-local OpenSpec binary is missing. | Run `pumuki bootstrap --enterprise` or install the required package in the repo. |
+| PRE_PUSH blocks due to missing upstream | Branch has no tracking ref. | Run `git push --set-upstream origin <branch>`. |
+| Version drift in `doctor` | Package/runtime/lifecycle versions differ. | Use the printed `alignmentCommand`. |
+| Hook blocks unrelated brownfield debt | Scope classification may be wrong. | Capture command, staged files and JSON output; open an issue. |
+| `.ai_evidence.json` changes during docs-only work | Evidence refresh behavior is active. | Review the diff and stage only when the evidence belongs to the slice. |
+| MCP port conflict | Another instance is running. | Use `PUMUKI_ENTERPRISE_MCP_PORT=0` for dynamic port allocation. |
+
+Bug report template:
+
+```text
+Repository:
+Branch:
+Pumuki version:
+Command:
+Expected result:
+Actual result:
+Staged files:
+Relevant output:
+Evidence file present:
+```
 
-### Capture 5 — Option 1 Final Summary (PASS)
+## Documentation
 
-![Option 1 Final Summary Pass](assets/readme/menu-option1/05-option1-final-summary-pass.png)
+Start here:
 
-### Capture 6 — Menu Status After PASS Run
+- [Operator Playbook](PUMUKI.md)
+- [Documentation Index](docs/README.md)
+- [Installation](docs/product/INSTALLATION.md)
+- [Usage](docs/product/USAGE.md)
+- [Architecture](docs/product/ARCHITECTURE.md)
+- [Configuration](docs/product/CONFIGURATION.md)
+- [API Reference](docs/product/API_REFERENCE.md)
+- [Testing](docs/product/TESTING.md)
+- [MCP Servers](docs/mcp/mcp-servers-overview.md)
+- [Rule Packs](docs/rule-packs/README.md)
+- [Governance Standards](docs/governance/CODE_STANDARDS.md)
+- [Contributing](docs/governance/CONTRIBUTING.md)
 
-![Menu After Pass Run](assets/readme/menu-option1/06-menu-after-run-pass.png)
+Optional training hub:
 
-Extended annotated walkthrough:
+- [Pumuki course in Stack My Architecture](https://stack-my-architecture-hub.vercel.app/pumuki/)
 
-- `docs/operations/framework-menu-consumer-walkthrough.md`
+## Contributing
 
-## Enterprise Operations Baseline
+For high-quality contributions:
 
-Pumuki production SaaS operation baseline is defined in:
+1. Read [Contributing](docs/governance/CONTRIBUTING.md) and [Code Standards](docs/governance/CODE_STANDARDS.md).
+2. Work on a dedicated branch.
+3. Keep each change atomic.
+4. Add focused regression coverage for behavior changes.
+5. Run the relevant local validation commands.
+6. Open a PR with problem, approach and evidence.
 
-- `docs/operations/production-operations-policy.md`
+Maintainer validation commands:
 
-Highlights:
+```bash
+npm run -s typecheck
+npm run -s test:deterministic
+npm run -s validation:package-manifest
+npm run -s smoke:pumuki-surface
+```
 
-- Minimum SLO/SLA targets for ingestion availability, latency, freshness, and isolation.
-- Severity model (`SEV1/SEV2/SEV3`) with response and RCA expectations.
-- Mandatory controls for tenant/repo isolation, auth policy, idempotency, and auditing.
-- Go-live checklist and rollback requirements.
+For release-grade validation in this repository:
 
-## Troubleshooting
+```bash
+npm run -s validation:local-merge-bar
+npm publish --dry-run --access public
+```
 
-- `OpenSpec change "<id>" not found`: ensure `openspec/changes/<id>` exists before opening session.
-- `SDD_SESSION_MISSING`: open and validate session first.
-- `pre-push blocked: branch has no upstream`: run `git push --set-upstream origin <branch>`.
-- `Missing required argument --repo` / `--repo-path`: pass required flags for validation scripts.
-- Legacy parity report usage requires `--legacy=<path>` and `--enterprise=<path>` (equals form).
-- If menu v2 rendering fails, Pumuki falls back to classic UI.
-
-## Documentation Index
-
-- Installation: `docs/product/INSTALLATION.md`
-- Usage: `docs/product/USAGE.md`
-- Backlog tooling quick nav (incluye snippet terminal): `docs/product/USAGE.md#backlog-tooling`
-- Backlog reasons shared module: `docs/product/USAGE.md#backlog-reasons`
-- Testing: `docs/product/TESTING.md`
-- API reference: `docs/product/API_REFERENCE.md`
-- Architecture: `docs/product/ARCHITECTURE.md`
-- Configuration: `docs/product/CONFIGURATION.md`
-- Code standards: `docs/governance/CODE_STANDARDS.md`
-- Branch protection: `docs/governance/BRANCH_PROTECTION_GUIDE.md`
-- MCP servers: `docs/mcp/mcp-servers-overview.md`
-- MCP evidence server: `docs/mcp/evidence-context-server.md`
-- MCP consumption: `docs/mcp/agent-context-consumption.md`
-- Evidence schema v2.1: `docs/mcp/ai-evidence-v2.1-contract.md`
-- Operations policy (SLA/SLO): `docs/operations/production-operations-policy.md`
-- Release notes: `docs/operations/RELEASE_NOTES.md`
-- Changelog: `CHANGELOG.md`
-
-## Collaboration
-
-Contributions are welcome. For high-quality collaboration:
-
-1. Read `docs/governance/CONTRIBUTING.md` and `docs/governance/CODE_STANDARDS.md`.
-2. Create a dedicated branch per change.
-3. Keep scope focused and include deterministic evidence when relevant.
-4. Before opening a PR, run at least:
-   - `npm run typecheck`
-   - `npm run -s test:backlog-tooling`
-   - `npm run test:operational-memory`
-   - `npm run test:saas-ingestion`
-5. Open a PR with clear problem statement, approach, and validation evidence.
+Publishing to npm is a separate release operation and may require registry auth/MFA handling.
 
 ## Support and Security
 
-- Functional/usage issues: open a GitHub issue with reproducible steps.
-- Enterprise diagnostics: include generated reports from `.audit-reports` when applicable.
-- Security-sensitive findings: use GitHub Security Advisories for coordinated disclosure.
+- Functional issues: use [GitHub Issues](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/issues).
+- Security-sensitive issues: use GitHub Security Advisories or coordinated private disclosure.
+- Enterprise diagnostics: attach command output and evidence excerpts, but never include secrets.
 
 ## License
 
-MIT. See `LICENSE`.
-
-## If Pumuki Helped You
-
-If this project was useful for your team, please consider leaving a GitHub star:
-
-[Star Pumuki on GitHub](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks)
+MIT. See [LICENSE](LICENSE).

package/assets/readme/pumuki-governance-flow.svg

@@ -0,0 +1,71 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="760" viewBox="0 0 1600 760" role="img" aria-label="Pumuki governance flow">
+  <defs>
+    <style>
+      .bg { fill: #0b0f14; }
+      .panel { fill: #111827; stroke: #263244; stroke-width: 2; }
+      .box { fill: #0f172a; stroke: #38bdf8; stroke-width: 2; }
+      .box2 { fill: #102118; stroke: #34d399; stroke-width: 2; }
+      .box3 { fill: #221a10; stroke: #f59e0b; stroke-width: 2; }
+      .title { fill: #f8fafc; font: 700 42px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .sub { fill: #93c5fd; font: 600 24px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .h { fill: #e5e7eb; font: 700 23px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .t { fill: #cbd5e1; font: 18px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .muted { fill: #94a3b8; font: 16px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .arrow { stroke: #64748b; stroke-width: 4; fill: none; marker-end: url(#arrowhead); }
+    </style>
+    <marker id="arrowhead" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
+      <path d="M 0 0 L 10 4 L 0 8 z" fill="#64748b" />
+    </marker>
+  </defs>
+
+  <rect class="bg" width="1600" height="760" rx="28" />
+  <rect class="panel" x="44" y="44" width="1512" height="672" rx="24" />
+
+  <text class="title" x="90" y="116">Pumuki Enterprise Governance Flow</text>
+  <text class="sub" x="90" y="158">One deterministic contract for humans, AI agents, hooks and CI</text>
+
+  <rect class="box" x="90" y="230" width="260" height="128" rx="16" />
+  <text class="h" x="118" y="274">1. Facts</text>
+  <text class="t" x="118" y="310">Git scope</text>
+  <text class="t" x="118" y="338">Repo state</text>
+
+  <rect class="box" x="440" y="230" width="260" height="128" rx="16" />
+  <text class="h" x="468" y="274">2. Rules</text>
+  <text class="t" x="468" y="310">Skills</text>
+  <text class="t" x="468" y="338">Rule packs</text>
+
+  <rect class="box3" x="790" y="230" width="260" height="128" rx="16" />
+  <text class="h" x="818" y="274">3. Gate</text>
+  <text class="t" x="818" y="310">PASS / WARN / BLOCK</text>
+  <text class="t" x="818" y="338">Stage policy</text>
+
+  <rect class="box2" x="1140" y="230" width="260" height="128" rx="16" />
+  <text class="h" x="1168" y="274">4. Evidence</text>
+  <text class="t" x="1168" y="310">ai_evidence v2.1</text>
+  <text class="t" x="1168" y="338">Traceable output</text>
+
+  <path class="arrow" d="M 355 294 L 430 294" />
+  <path class="arrow" d="M 705 294 L 780 294" />
+  <path class="arrow" d="M 1055 294 L 1130 294" />
+
+  <rect class="box" x="150" y="470" width="330" height="120" rx="16" />
+  <text class="h" x="178" y="512">Delivery surfaces</text>
+  <text class="t" x="178" y="548">PRE_WRITE, PRE_COMMIT</text>
+  <text class="t" x="178" y="576">PRE_PUSH, CI, audit</text>
+
+  <rect class="box2" x="635" y="470" width="330" height="120" rx="16" />
+  <text class="h" x="663" y="512">Developer UX</text>
+  <text class="t" x="663" y="548">Menu, notifications</text>
+  <text class="t" x="663" y="576">Actionable remediation</text>
+
+  <rect class="box" x="1120" y="470" width="330" height="120" rx="16" />
+  <text class="h" x="1148" y="512">Automation</text>
+  <text class="t" x="1148" y="548">MCP, adapters</text>
+  <text class="t" x="1148" y="576">Telemetry, diagnostics</text>
+
+  <path class="arrow" d="M 920 364 L 920 414 L 315 414 L 315 460" />
+  <path class="arrow" d="M 1270 364 L 1270 414 L 800 414 L 800 460" />
+  <path class="arrow" d="M 1270 364 L 1285 414 L 1285 460" />
+
+  <text class="muted" x="90" y="660">Baseline is IDE-agnostic. Client-specific adapters are opt-in.</text>
+</svg>

package/integrations/config/skillsRuleClassification.ts

@@ -235,6 +235,109 @@ const STUDY_BEFORE_DETECTOR_RULE_IDS = new Set<string>([
 const requiresStudyBeforeDetector = (rule: SkillsCompiledRule): boolean =>
   STUDY_BEFORE_DETECTOR_RULE_IDS.has(rule.id);
 
+const IOS_POSITIVE_CODE_GUIDANCE_PATTERNS: ReadonlyArray<RegExp> = [
+  /\basyncsequence\b/,
+  /\basyncstream\b/,
+  /\bcopy[-\s]on[-\s]write\b/,
+  /\bequatable[-\s]hashable\b/,
+  /\bnil[-\s]coalescing\b/,
+  /\bnumberformatter\b/,
+  /\boperators[-\s]map[-\s]filter[-\s]flatmap\b/,
+  /\boptional[-\s]chaining\b/,
+  /\bresult[-\s]builders?\b/,
+  /\bcustom[-\s]view[-\s]modifiers?\b.*\breutilizar\b/,
+  /\bdeclarativo\b.*\bui\b/,
+  /\bequatable[-\s]views?\b/,
+  /\bextensions?\b.*\bagrupar\b.*\bfuncionalidad\b/,
+  /\bfactory[-\s]pattern\b/,
+  /\bif[-\s]let\b.*\bunwrap\b/,
+  /\binmutabilidad\b.*\blet\b.*\bvar\b/,
+  /\bmark\b.*\borganizar\b.*\bco[-\s]?digo\b/,
+  /\bmemoization\b/,
+  /\bmvvm\b.*\b(viewmodel|swiftui|combine)\b/,
+  /\bpage[-\s]object[-\s]pattern\b/,
+  /\bpreferencekeys?\b/,
+  /\bpreferences\b.*\bchild[-\s]parent\b/,
+  /\bprotocol[-\s]extensions?\b/,
+  /\bprotocols[-\s]over[-\s]inheritance\b/,
+  /\bpublished\b.*\bviewmodels?\b.*\bbinding\b/,
+  /\bstruct\b.*\bclass\b.*\bidentity\b/,
+  /\buse[-\s]cases?\b.*\b[A-Za-z0-9_]*usecase\b/,
+  /\bviewmodels?[-\s]por[-\s]pantalla\b/,
+  /\bviewmodifiers?[-\s]nativos?\b/,
+  /\bviewthatfits\b/,
+  /\bviper\b.*\boverkill\b/,
+];
+
+const IOS_AUDITED_POSITIVE_LANGUAGE_GUIDANCE_PATTERNS: ReadonlyArray<RegExp> = [
+  /\basyncsequence\b/,
+  /\basyncstream\b/,
+  /\bcopy[-\s]on[-\s]write\b/,
+  /\bequatable[-\s]hashable\b/,
+  /\bnil[-\s]coalescing\b/,
+  /\bnumberformatter\b/,
+  /\boperators[-\s]map[-\s]filter[-\s]flatmap\b/,
+  /\boptional[-\s]chaining\b/,
+  /\bpublishers[-\s]asyncsequence\b/,
+  /\bresult[-\s]builders?\b/,
+];
+
+const IOS_AUDITED_POSITIVE_ARCHITECTURE_STYLE_GUIDANCE_PATTERNS: ReadonlyArray<RegExp> = [
+  /\bcustom[-\s]view[-\s]modifiers?\b.*\breutilizar\b/,
+  /\bdeclarativo\b.*\bui\b/,
+  /\bequatable[-\s]views?\b/,
+  /\bextensions?\b.*\bagrupar\b.*\bfuncionalidad\b/,
+  /\bfactory[-\s]pattern\b/,
+  /\bif[-\s]let\b.*\bunwrap\b/,
+  /\binmutabilidad\b.*\blet\b.*\bvar\b/,
+  /\bmark\b.*\borganizar\b.*\bco[-\s]?digo\b/,
+  /\bmemoization\b/,
+  /\bmvvm\b.*\b(viewmodel|swiftui|combine)\b/,
+  /\bpage[-\s]object[-\s]pattern\b/,
+  /\bpreferencekeys?\b/,
+  /\bpreferences\b.*\bchild[-\s]parent\b/,
+  /\bprotocol[-\s]extensions?\b/,
+  /\bprotocols[-\s]over[-\s]inheritance\b/,
+  /\bpublished\b.*\bviewmodels?\b.*\bbinding\b/,
+  /\bstruct\b.*\bclass\b.*\bidentity\b/,
+  /\buse[-\s]cases?\b.*\b[A-Za-z0-9_]*usecase\b/,
+  /\bviewmodels?[-\s]por[-\s]pantalla\b/,
+  /\bviewmodifiers?[-\s]nativos?\b/,
+  /\bviewthatfits\b/,
+  /\bviper\b.*\boverkill\b/,
+];
+
+const isAuditedIosPositiveLanguageGuidance = (rule: SkillsCompiledRule): boolean => {
+  if (rule.platform !== 'ios') {
+    return false;
+  }
+
+  const haystack = normalizeText(`${rule.id} ${rule.description} ${rule.sourceSkill}`);
+  return IOS_AUDITED_POSITIVE_LANGUAGE_GUIDANCE_PATTERNS.some((pattern) => pattern.test(haystack));
+};
+
+const isAuditedIosPositiveArchitectureStyleGuidance = (rule: SkillsCompiledRule): boolean => {
+  if (rule.platform !== 'ios') {
+    return false;
+  }
+
+  const haystack = normalizeText(`${rule.id} ${rule.description} ${rule.sourceSkill}`);
+  return IOS_AUDITED_POSITIVE_ARCHITECTURE_STYLE_GUIDANCE_PATTERNS.some((pattern) => pattern.test(haystack));
+};
+
+const requiresIosPositiveCodeGuidanceAudit = (rule: SkillsCompiledRule): boolean => {
+  if (rule.platform !== 'ios') {
+    return false;
+  }
+
+  if (normalizeText(rule.id).includes('-md-')) {
+    return false;
+  }
+
+  const haystack = normalizeText(`${rule.id} ${rule.description} ${rule.sourceSkill}`);
+  return IOS_POSITIVE_CODE_GUIDANCE_PATTERNS.some((pattern) => pattern.test(haystack));
+};
+
 const isNonCodeRule = (rule: SkillsCompiledRule): boolean => {
   const haystack = normalizeText(`${rule.id} ${rule.description} ${rule.sourceSkill}`);
   return NON_CODE_RULE_PATTERNS.some((pattern) => pattern.test(haystack));
@@ -317,6 +420,36 @@ const classifyRule = (rule: SkillsCompiledRule): ClassifiedSkillsRule => {
     };
   }
 
+  if (isAuditedIosPositiveLanguageGuidance(rule) || isAuditedIosPositiveArchitectureStyleGuidance(rule)) {
+    return {
+      ruleId: rule.id,
+      platform: rule.platform,
+      sourceSkill: rule.sourceSkill,
+      sourcePath: rule.sourcePath,
+      evaluationMode,
+      severity: rule.severity,
+      status: 'NO_ES_REGLA_DE_CODIGO',
+      reason:
+        'Audited iOS positive guidance; absence is not a safe runtime violation and related negative patterns must be enforced by specific detectors.',
+      astNodeIds,
+    };
+  }
+
+  if (requiresIosPositiveCodeGuidanceAudit(rule)) {
+    return {
+      ruleId: rule.id,
+      platform: rule.platform,
+      sourceSkill: rule.sourceSkill,
+      sourcePath: rule.sourcePath,
+      evaluationMode,
+      severity: rule.severity,
+      status: 'REQUIERE_ESTUDIO',
+      reason:
+        'iOS positive code guidance needs explicit audit before classifying it as non-runtime or implementing a detector.',
+      astNodeIds,
+    };
+  }
+
   if (isNonCodeRule(rule)) {
     return {
       ruleId: rule.id,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pumuki",
-  "version": "6.3.375",
-  "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.",
+  "version": "6.3.377",
+  "description": "Enterprise governance framework for AI-assisted software delivery with Git hooks, SDD/OpenSpec, AST intelligence, evidence, MCP and multi-platform rule enforcement.",
   "main": "index.js",
   "bin": {
     "pumuki": "bin/pumuki.js",
@@ -184,7 +184,14 @@
     "kotlin",
     "react",
     "nextjs",
-    "nestjs"
+    "nestjs",
+    "ai-governance",
+    "ai-assisted-development",
+    "software-delivery",
+    "sdd",
+    "openspec",
+    "mcp",
+    "evidence"
   ],
   "author": {
     "name": "Juan Carlos Merlos Albarracín",