pumuki 6.3.97 → 6.3.99

package/README.md

@@ -32,7 +32,7 @@ Elige un perfil y profundiza en los enlaces; **no** repite aquí reglas largas (
 
 | Perfil | Qué instalar / arrancar | Stages habituales | Opcional típico |
 |--------|-------------------------|-------------------|-----------------|
-| **Mínimo** | `npm install --save-exact pumuki` (en repos Git el `postinstall` puede ejecutar `pumuki install` para hooks y lifecycle). | 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. |
+| **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). |
 
@@ -50,6 +50,8 @@ Cinco entradas que cubren el 80 % del día a día en un consumidor; el detalle e
 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.
 
+**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).
+
 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).
 
 ## 5-Minute Quick Start (Consumer)
@@ -69,7 +71,7 @@ npx --yes pumuki status
 npx --yes pumuki doctor --json
 ```
 
-Desde **6.3.63**, `npm install` en la raíz de un repo **Git** dispara un `postinstall` que ejecuta **`pumuki install` solo** (hooks `pre-commit` / `pre-push`, lifecycle, evidencia cuando aplica). **Pumuki no depende de ningún IDE** para el baseline: no toca `.cursor/` ni otros ficheros de editor por defecto. 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). Tras install, si no existía, aparece **`.pumuki/adapter.json`** con los comandos de hooks y **MCP stdio** para referencia o para clientes que los registren manualmente. Para generar también config de IDE: **`pumuki install --with-mcp --agent=cursor`** (u otro) o **`pumuki bootstrap --enterprise --agent=…`**. 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.
+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):
 

package/VERSION

@@ -1 +1 @@
-v6.3.85
+v6.3.99

package/docs/README.md

@@ -4,6 +4,10 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 
 ## Si buscas algo concreto
 
+- Quiero la **intención de producto canónica** (qué debe cumplir Pumuki en cualquier repo, sin repetir manifiesto en cada sesión):
+  - `docs/product/USAGE.md` (sección **Product intent**)
+- Quiero **auditar todo el árbol trackeado** desde CLI (no solo staged):
+  - `docs/product/USAGE.md` (sección **Full-repository audit**), comando `pumuki audit`
 - Quiero límites del producto, perfil de adopción y comandos mínimos (sin leer todo el README largo):
   - `README.md` (secciones **Qué NO es Pumuki**, **Rutas de adopción**, **Comandos esenciales**)
 - Quiero instalar y arrancar Pumuki en un repo consumidor:
@@ -34,13 +38,13 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 - Quiero runbooks de validación:
   - `docs/validation/README.md`
   - `docs/validation/ios-avdlee-parity-matrix.md`
+  - Smoke de superficie CLI + hooks (`npm run smoke:pumuki-surface`, opcional consumidor / bins instalados: ver `docs/validation/README.md`)
+  - Barra local sin Actions: `npm run -s validation:local-merge-bar` (ver `docs/validation/README.md` § GitHub Actions y cuota)
 
 - Quiero saber en qué estamos ahora:
-  - `PUMUKI-RESET-MASTER-PLAN.md` en la raíz del repo como artefacto operativo local y única fuente viva del tracking interno
-- Quiero contexto histórico o materiales de seguimiento retirados:
-  - Referencia histórica: `docs/tracking/plan-activo-de-trabajo.md`
-  - Quiero el seguimiento del curso Stack My Architecture (Pumuki), iniciativa formativa aparte del espejo operativo:
-  - Curso Stack My Architecture: `docs/tracking/plan-curso-pumuki-stack-my-architecture.md`
+  - `docs/tracking/plan-activo-de-trabajo.md`
+- Quiero el seguimiento del curso Stack My Architecture (Pumuki), iniciativa formativa aparte del espejo operativo:
+  - `docs/tracking/plan-curso-pumuki-stack-my-architecture.md`
 
 ## Estructura oficial
 
@@ -67,10 +71,10 @@ Mapa corto y humano de la documentación oficial de Pumuki.
   - Skills vendorizadas que el repo usa como contrato local.
 
 - `docs/tracking/`
-  - Material histórico o formativo; no actúa como backlog vivo del producto.
-  - Fuente viva del tracking interno: `PUMUKI-RESET-MASTER-PLAN.md` en la raíz del repo.
-  - Documento retirado: `docs/tracking/plan-activo-de-trabajo.md`.
-  - Material del curso: `docs/tracking/plan-curso-pumuki-stack-my-architecture.md`.
+  - Seguimiento permitido y solo el imprescindible.
+  - Espejo operativo de producto y consumidores: `docs/tracking/plan-activo-de-trabajo.md` (unica fuente de verdad para ese ambito).
+  - Curso Pumuki (Stack My Architecture): diseño pedagógico + seguimiento de entrega en `docs/tracking/plan-curso-pumuki-stack-my-architecture.md` (no sustituye al plan activo).
+  - Regla hard: solo puede existir una tarea `🚧` en cada documento de seguimiento que lo use.
 
 ## Fuera de `docs/`
 

package/docs/operations/RELEASE_NOTES.md

@@ -1,40 +1,3 @@
-## 2026-04-20 (v6.3.97)
-- **Adapter MCP enterprise activo por defecto**: `pumuki install` ya no genera un comando enterprise MCP que arranca en modo baseline. El `adapter.json` y las entradas MCP de IDE exportan ahora `PUMUKI_EXPERIMENTAL_MCP_ENTERPRISE=advisory`, de modo que el cliente ve `ai_gate_check`, `pre_flight_check` y `auto_execute_ai_start` sin intervención manual adicional.
-- **Rollout recomendado**: publicar `pumuki@6.3.97`, repin inmediato en `Flux_training` y verificar `tools/list` arrancando exactamente el comando de `.pumuki/adapter.json`; debe dejar de devolver solo `check_sdd_status`, `validate_and_fix`, `sync_branches` y `cleanup_stale_branches`.
-
-## 2026-04-20 (v6.3.96)
-- **Diagnóstico explícito de skills faltantes**: `status`, `doctor` y el AI gate ya no degradan a señales genéricas cuando falta una skill requerida o su fuente es ilegible; ahora emiten `SKILLS_REQUIRED_SOURCE_MISSING` o `SKILLS_REQUIRED_SOURCE_UNREADABLE` con nombre de skill, ruta concreta y resolución accionable.
-- **Rollout recomendado**: publicar `pumuki@6.3.96`, repin inmediato en `Flux_training` y repetir la repro del repo sin `docs/codex-skills`, confirmando que `status --json` y `doctor --json` incluyen la ruta `docs/codex-skills/windsurf-rules-backend.md` en `skills_contract.source_diagnostics`.
-
-## 2026-04-20 (v6.3.95)
-- **Enforcement operativo de trazabilidad contractual**: `pumuki sdd evidence` exige ahora `--traceability-markdown=<path>` cuando el repositorio declara en `AGENTS.md` la matriz mínima `ARCHIVO | SKILL | REGLA | EVIDENCIA | ESTADO`; el comando falla si falta la cabecera exacta o si no existe al menos una fila real.
-- **Rollout recomendado**: publicar `pumuki@6.3.95`, repin inmediato en `Flux_training` y repetir la doble repro de `pumuki sdd evidence`: sin `--traceability-markdown` debe bloquear, y con un markdown repo-local que contenga la matriz contractual debe pasar.
-
-## 2026-04-20 (v6.3.94)
-- **Subtitle de bloqueo 100% en español**: la causa primaria visible de notificaciones ya traduce explícitamente los mensajes exactos de `console.log usage is not allowed in frontend code.` y `...backend code.` antes de construir el `subtitle`, evitando el último escape de copy inglés en bloqueos reales de frontend/backend.
-- **Rollout recomendado**: publicar `pumuki@6.3.94`, repin inmediato en `Flux_training` y repetir un rojo real de frontend con `PUMUKI_SKIP_CHAINED_PRE_WRITE=1 pnpm exec pumuki-pre-commit`, confirmando que el `subtitle` contiene `Se detectó uso de "console.log" en frontend.` y no la frase inglesa raw.
-
-## 2026-04-20 (v6.3.93)
-- **Tracking terminal 100% en español**: las violaciones de repo policy `TRACKING_CANONICAL_SOURCE_CONFLICT`, `TRACKING_CANONICAL_FILE_MISSING` y `TRACKING_CANONICAL_IN_PROGRESS_INVALID` traducen ya la línea `[ERROR]` del gate en terminal, no solo el banner/modal.
-- **Rollout recomendado**: publicar `pumuki@6.3.93`, repin inmediato en `Flux_training` y repetir el bloqueo con doble `🚧` para confirmar que desaparece la frase inglesa `Tracking canonical file must contain exactly one in-progress task`.
-
-## 2026-04-20 (v6.3.92)
-- **Purge real de uninstall**: `pumuki uninstall --purge-artifacts` elimina ya los artefactos bootstrap locales `.pumuki/adapter.json` y `.pumuki/bootstrap-manifest.json` cuando no están trackeados, en vez de dejar una instalación “medio desinstalada”.
-- **Rollout recomendado**: publicar `pumuki@6.3.92`, repin inmediato en `Flux_training` y repetir `install -> uninstall --purge-artifacts` comprobando `adapter=no` y `manifest=no` al final.
-
-## 2026-04-20 (v6.3.91)
-- **Observabilidad de skills alineada**: `status --json` y `doctor --json` dejan visible `governanceObservation.skills_contract` cuando la evidencia y el lock efectivo de skills muestran un contrato activo; el lifecycle ya no aparenta `NOT_APPLICABLE` mientras el gate real bloquea violaciones frontend/backend.
-- **Rollout recomendado**: publicar `pumuki@6.3.91`, repin inmediato en `Flux_training` y repetir la repro con rojo frontend staged para confirmar `skills_contract.enforced=true`, `skills_contract.status=FAIL` y `attention_codes` con `SKILLS_CONTRACT_INCOMPLETE`.
-
-## 2026-04-20 (v6.3.89)
-- **Aislamiento por worktree**: `pumuki install` detecta worktrees sin `core.hooksPath` explícito y fija un `core.hooksPath` local a `.pumuki/git-hooks`, evitando que los hooks gestionados se escriban en `.git/hooks` del checkout principal compartido.
-- **Rollback limpio**: `pumuki uninstall` retira ese `core.hooksPath` solo si fue creado por Pumuki para el worktree.
-- **Rollout recomendado**: publicar `pumuki@6.3.89`, repin inmediato en `Flux_training` y repetir la repro de worktree (`install`, `bootstrap-manifest`, `status --json`, checksums de hooks en checkout principal).
-
-## 2026-04-20 (v6.3.87)
-- Cierra el segundo tramo de PUM-026: si PRE_WRITE solo arregla el receipt MCP y el gate pasa a verde, fuerza un refresh de paridad contra PRE_COMMIT antes del veredicto final.
-- Rollout recomendado: actualizar Flux_training y repetir la repro mínima de validate/pre-commit/.ai_evidence.
-
 # Release Notes (v2.x line)
 
 This file tracks the active deterministic framework line used in this repository.
@@ -43,46 +6,21 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 ## 2026-04 (CLI stability and macOS notifications)
 
-### 2026-04-20 (v6.3.86)
-
-- **Paridad de gate real**: `pumuki sdd validate --stage=PRE_WRITE --json` deja de devolver verde falso cuando el hook real bloquearía por evidencia o findings staged; ahora fuerza refresh de evidencia incluso si el `aiGate` inicial llega en `ALLOWED`.
-- **Evidencia consistente**: el envelope final de `validate` usa el resultado refrescado y `.ai_evidence.json` queda en `BLOCK` cuando el rojo real del consumer persiste.
-- **Rollout recomendado**: publicar `pumuki@6.3.86`, repin inmediato en `Flux_training` y revalidar con un rojo frontend staged (`validate PRE_WRITE`, `pre-commit`, `.ai_evidence.json`, `status`, `doctor`).
+### 2026-04-22 (v6.3.99)
 
-### 2026-04-20 (v6.3.85)
+- **Hotfix de coerción temprana:** `PRE_WRITE` deja de parecer advisory cuando realmente está activado en `strict`, y el arranque agentic devuelve fallo real al bloquear.
+- **Rollout recomendado:** publicar `pumuki@6.3.99` y repin inmediato en `RuralGo`, validando `pumuki:status`, `pumuki:doctor`, `pre-commit` y `pre-push` con el fix de `PUMUKI-INC-079`.
 
-- **Tracking con viñeta reconocido**: el enforcement ya cuenta correctamente `- [🚧] - tarea` como única tarea activa válida en el MD canónico, eliminando falsos `count=0` en consumers que usan ese formato.
-- **Causa visible en español**: los bloqueos de tracking `TRACKING_CANONICAL_SOURCE_CONFLICT` y `TRACKING_CANONICAL_IN_PROGRESS_INVALID` renderizan ya el texto final en español en banner y modal.
-- **Rollout recomendado**: publicar `pumuki@6.3.85`, repin en `R_GO` y `Flux_training`, y confirmar que el bloqueo residual ya no mezcla inglés y español ni falla por ignorar la fila `- [🚧] -`.
+### 2026-04-11 (v6.3.72)
 
-### 2026-04-20 (v6.3.84)
-
-- **Tracking en español**: `TRACKING_CANONICAL_SOURCE_CONFLICT` y `TRACKING_CANONICAL_IN_PROGRESS_INVALID` ya renderizan una causa 100% en español en el banner y en el modal macOS.
-- **Rollout recomendado**: publicar `pumuki@6.3.84`, repin inmediato en los consumers donde el bloqueo de tracking sigue vivo y verificar que la notificación visible deja de mezclar inglés y español.
-
-### 2026-04-20 (v6.3.83)
-
-- **Copy 100% en español**: `gate.blocked` ya no filtra `causeMessage` ni `remediation` en inglés cuando el código no está mapeado; el fallback visible para usuario final queda íntegramente en español.
-- **Botones validados en framework**: `Desactivar` y `Silenciar 30 min` se han revalidado extremo a extremo dentro del runtime de notificaciones; `Desactivar` bloquea emisiones posteriores y `Silenciar 30 min` reabre automáticamente al expirar la ventana.
-- **Rollout recomendado**: publicar `pumuki@6.3.83`, repin inmediato en consumers activos y comprobar en al menos un consumer real que el diálogo macOS deja de mostrar spaninglish y respeta las acciones del usuario.
-
-### 2026-04-17 (v6.3.81)
-
-- **Causa 100% en español**: la notificación `gate.blocked` traduce explícitamente `EVIDENCE_GATE_BLOCKED` y también los mensajes legacy equivalentes, evitando el spanglish `Cause: Evidence AI gate status is BLOCKED.` en macOS.
-- **Rollout recomendado**: publicar `pumuki@6.3.81` y repin rápido `RuralGo -> SAAS -> Flux`, revalidando la notificación bloqueante y `status/doctor` en cada consumer.
-
-### 2026-04-17 (v6.3.80)
-
-- **Tracking canónico**: la línea viva acepta el formato contractual `[🚧] - tarea` en el plan maestro y en tablas con backticks, tanto en el parser de tracking como en el guardrail shell de una sola task activa.
-- **Notificaciones bloqueantes**: copy y remediaciones de `gate.blocked` salen en español cuando el payload legacy llega en inglés; el banner macOS corta por palabra y conserva una solución breve y accionable.
-- **Rollout recomendado**: publicar `pumuki@6.3.80` y repin ordenado `RuralGo -> SAAS -> Flux`, revalidando después `pumuki status`, `pumuki doctor` y hooks Git en cada consumer.
-
-### 2026-04-16 (v6.3.78)
-
-- **Slice S1 consolidada**: `status`, `doctor`, `PRE-FLIGHT CHECK`, menú `Consumer` y menú `Advanced` muestran el mismo bloque canónico de governance sin duplicar lógica de cálculo.
-- **Runtime del menú**: `Consumer` conserva `lastPreflight` y lo reutiliza en superficies derivadas para mantener paridad visible de `truth / next action / policy-as-code / experimentales`.
-- **Base de release correcta**: la publicación se prepara desde `release/6.3.78` recortada sobre `develop` ya alineado con la línea viva `release/6.3.77`.
-- **Rollout recomendado**: publicar `pumuki@6.3.78` y repin ordenado `RuralGo -> SAAS -> Flux`, validando después `pumuki status`, `pumuki doctor` y hooks Git en cada consumer.
+- **Tarball npm**: `package.json` → `files` incluye `AGENTS.md`, `CHANGELOG.md` y `docs/tracking/plan-curso-pumuki-stack-my-architecture.md` para lectura canónica vía npm / jsDelivr sin depender solo del repo Git.
+- **`gate.blocked` (macOS)**: banner de Notification Center **y** modal por defecto (evita cero notificaciones si el modal no llega a mostrarse desde un hook); dedupe opcional: `PUMUKI_MACOS_GATE_BLOCKED_BANNER_DEDUPE=1`.
+- **Modal Swift**: `NSAlert.runModal()` en lugar de panel flotante para que los botones del diálogo respondan de forma fiable.
+- **Postinstall consumer**: por defecto `pumuki install --with-mcp --agent=repo` y fusión conservadora en `.pumuki/adapter.json` (`json-merge`); opt-out `PUMUKI_POSTINSTALL_SKIP_MCP=1`.
+- **Validación local**: `smoke:pumuki-surface` / `smoke:pumuki-surface-installed` y `validation:local-merge-bar` (sin depender de minutos de Actions). Detalle en `docs/validation/README.md`.
+- **Tests en macOS:** `integrations/lifecycle/__tests__/cli.test.ts` evita notificaciones reales del sistema (`PUMUKI_DISABLE_SYSTEM_NOTIFICATIONS` en hooks) para que `npm test` / la barra local no queden colgados en PRE_WRITE strict.
+- **Menú / matriz consumer**: opciones motor `11–14`, matriz baseline alineada, vista classic opcional, etc. (ver `CHANGELOG.md`).
+- **Rollout**: `pumuki@6.3.72`; `npm publish` cuando el tarball incluya lo anterior; luego `pumuki doctor --json` + repin en consumidores (p. ej. RuralGO).
 
 ### 2026-04-06 (v6.3.71)
 
@@ -847,5 +785,3 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 - Legacy 5.3.4 migration/release notes were removed from active docs to avoid drift.
 - Historical commit trace remains available in Git history.
-
-- 6.3.88: PUM-027 cierra el caso MCP degradado; sin .pumuki/adapter.json el gate bloquea y ya no regenera mcp-ai-gate-receipt.

package/docs/product/HOW_IT_WORKS.md

@@ -51,6 +51,12 @@ Pipeline:
 
 Policy source: `integrations/gate/stagePolicies.ts`.
 
+### `pumuki audit` (full tracked tree)
+
+The lifecycle command **`pumuki audit`** runs `runPlatformGate` with **`GateScope` = `repo`**: facts come from **`git ls-files`** filtered by the default code extensions, using the working tree contents of those paths. It is **not** the same as the `PRE_COMMIT` hook, which uses **`staged`** scope only.
+
+JSON output includes how many **untracked** paths would have matched those extensions (`untracked_matching_extensions_count`); they are still excluded from facts unless you use a different scope (for example consumer menu options that include unstaged paths).
+
 ## Main runtime components
 
 - `integrations/git/runPlatformGate.ts`

package/docs/product/INSTALLATION.md

@@ -51,7 +51,7 @@ If both commands pass, the workspace is ready.
 npm install --save-exact pumuki
 ```
 
-The package `postinstall` runs **`pumuki install` only** (Git hooks + lifecycle wiring). Hooks chain **`pumuki-pre-write`** then **`pumuki-pre-commit`** / **`pumuki-pre-push`** (IDE-agnostic). When missing, **`.pumuki/adapter.json`** is created with hook + **MCP stdio** command lines (any MCP client can use them). It does **not** write IDE-specific files; use step 2 or `pumuki install --with-mcp --agent=<name>` for that.
+The package `postinstall` runs baseline **`pumuki install`** by default (Git hooks + lifecycle wiring + **solo** **`.pumuki/adapter.json`**: hooks + **MCP stdio** command lines). MCP wiring is now opt-in: set `PUMUKI_POSTINSTALL_WITH_MCP=1` or `PUMUKI_POSTINSTALL_MCP_AGENT=repo|cursor|claude|codex` to add adapter/client wiring in postinstall. Eso es **agnóstico de IDE/CLI/extensión**: cualquier cliente MCP puede leer esas líneas o enlazarlas manualmente. En cada `npm install` que actualice `pumuki` (repin), el adapter se **fusiona** (`json-merge`) para no pisar claves propias del consumidor. Opt out del bloque MCP+wiring: `PUMUKI_POSTINSTALL_SKIP_MCP=1`. Ficheros propios de un IDE (p. ej. `.cursor/mcp.json`, `.claude/settings.json`): **`pumuki install --with-mcp --agent=cursor|claude|codex`** a mano o **`PUMUKI_POSTINSTALL_MCP_AGENT=cursor`** (u otro agente soportado) si quieres que el postinstall también los escriba.
 
 ### 2) Bootstrap managed lifecycle (recommended single command)
 

package/docs/product/USAGE.md

@@ -19,6 +19,25 @@ Stack My Architecture (optional training hub; includes the dedicated Pumuki cour
 - Public static site: `https://stack-my-architecture-hub.vercel.app/pumuki/`
 - Initiative tracking in this repo: `docs/tracking/plan-curso-pumuki-stack-my-architecture.md`
 
+## Product intent (canonical)
+
+This section is the **single owner-authored contract** for what Pumuki must optimize for across consumers. Agents and contributors should treat it as **source of truth** for expectations so the product owner does not have to restate it in every session.
+
+1. **Repo-agnostic governance** — The same deterministic pipeline (`Facts → Rules → Gate → evidence`) must behave coherently in **any** Git consumer repository. Success is not measured by a specific downstream repo name.
+
+2. **Honest scope** — “What was audited” must always be explicit:
+   - Hook stages use **Git-defined scopes** (for example `PRE_COMMIT` is **staged** only; see the table [Gate stages and policies](#gate-stages-and-policies)).
+   - Full-tree style evaluation uses **tracked files** resolved via Git (`git ls-files`) with the configured extension set; **untracked** paths are out of scope unless a feature explicitly documents otherwise.
+   - Do not equate “pre-commit blocked me” with “the whole codebase was audited”.
+
+3. **Signal over noise** — Findings should reflect **real risk** for the active platforms in that repo. Heuristic multi-platform activation must not drown single-stack repos; set **`PUMUKI_PIN_PLATFORMS`** to a comma-separated subset (`ios`, `android`, `backend`, `frontend`) to restrict which detected platforms are kept for rule loading (unknown tokens are ignored).
+
+4. **Upgrade hygiene** — After bumping the `pumuki` package version, consumers that keep `.pumuki/policy-as-code.json` under version control must **refresh signatures** with `pumuki policy reconcile` (use `--apply` when appropriate). A `POLICY_AS_CODE_SIGNATURE_MISMATCH` from an **stale contract** is not the same class of problem as a code violation.
+
+5. **Product-shaped UX** — **`pumuki audit`** is the canonical CLI for “audit the tracked codebase in this repo” (see [Full-repository audit](#full-repository-audit-cli)). Hooks still use **staged** or **range** scopes per stage; do not confuse them.
+
+If this section conflicts with a one-off chat instruction, **this section wins** unless the product owner explicitly updates it here.
+
 ## Prerequisites
 
 - Node.js `>=18`
@@ -43,6 +62,20 @@ npm ci
 
 Policy source: `integrations/gate/stagePolicies.ts`.
 
+## Full-repository audit (CLI)
+
+Use **`pumuki audit`** when you want the gate to evaluate **all Git-tracked** source files under the default extension set (see `DEFAULT_FACT_FILE_EXTENSIONS` in `integrations/git/runPlatformGateFacts.ts`), not only the staged diff.
+
+```bash
+pumuki audit [--stage=PRE_COMMIT|PRE_PUSH|CI] [--engine] [--json]
+```
+
+- **`--stage`**: policy thresholds for that stage (default **`PRE_COMMIT`**). `PRE_WRITE` is not supported here. Aliases from SDD (`GREEN`, `REFACTOR`, `CLOSE`) work the same as for `pumuki sdd validate`.
+- **`--engine`**: run with `audit_mode=engine` and AST heuristics widened (aligned with the consumer menu “engine” path). Default is **`gate`** (strict enforcement semantics).
+- **`--json`**: machine-readable payload including `files_scanned`, `untracked_matching_extensions_count` (untracked paths that match the extension filter are **not** scanned), and `policy_reconcile_hint` for signature drift.
+
+Platform noise control: set **`PUMUKI_PIN_PLATFORMS`** (comma-separated) before running, e.g. `export PUMUKI_PIN_PLATFORMS=frontend` in a TS-only UI repo.
+
 Coverage guardrail:
 
 - In `PRE_COMMIT`, `PRE_PUSH` and `CI`, Pumuki requires complete rule evaluation coverage.
@@ -130,7 +163,10 @@ Use `A` to switch to `Advanced` mode (full options), and `C` to return to `Consu
 Advanced mode options include short inline contextual help.
 Consumer mode is now a minimal read-only shell:
 
-- `1/2/3/4` are the canonical read-only gate flows
+- `1/2/3/4` are the canonical gate flows with **consumer preflight** before evaluation (labels state scope and PRE_COMMIT vs PRE_PUSH).
+- `11/12/13/14` run the **engine** with **no preflight**: staged only, unstaged only (index→working tree + untracked), full working tree under **PRE_COMMIT**, or **all tracked files** (full repo). They write `.ai_evidence.json` on **PRE_COMMIT** engine runs like other menu audits.
+- After each successful evidence read, the menu prints a **second panel** (“Classic evidence view”) with **ANSI-colored** enterprise/legacy severity counts, optional **platform** rows from `snapshot.platforms`, and a longer ranked violation list. Disable with `PUMUKI_MENU_VINTAGE_REPORT=0`.
+- Options **2** and **4** (PRE_PUSH): if outcome is **PASS** or **WARN**, a short hint explains that a **tracked** `.ai_evidence.json` may **not** be rewritten on disk; use `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1` for local debugging.
 - `8` exports the same evidence snapshot in markdown form
 - `5/6/7/9` remain available only as `Legacy Read-Only Diagnostics`
 
@@ -249,9 +285,9 @@ Stage mapping:
 If a scope is empty, the menu prints an explicit operational hint (`Scope vacío`), so `PASS` with zero findings is distinguishable from a clean repository scan.
 
 System notifications (macOS) can be enabled from advanced menu option `31` (persisted in `.pumuki/system-notifications.json`).
-On non-macOS platforms, the same payloads are written to **stderr** by default (visible in the terminal) because there is no native banner API. Set `PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` to silence that path (delivery reports `unsupported-platform` on those OSes). On macOS, set `PUMUKI_NOTIFICATION_STDERR_MIRROR=1` to duplicate **any** notification payload to stderr in addition to the system notification. For **`gate.blocked`** specifically, stderr mirroring is **on by default** when the macOS path reports success (so a failed push/commit still prints a `[pumuki]` block in the terminal even if the banner does not appear); disable only that default with `PUMUKI_DISABLE_GATE_BLOCKED_STDERR_MIRROR=1`. The **blocked modal** (Swift floating / AppleScript) with **Desactivar / Silenciar 30 min / Mantener activas** is **on by default** whenever notifications are enabled and `blockedDialogEnabled` is omitted in `.pumuki/system-notifications.json`. Turn it off with `"blockedDialogEnabled": false` or `PUMUKI_MACOS_BLOCKED_DIALOG=0`. Ensure the terminal app is allowed to show notifications in **System Settings → Notifications**.
-Blocked notifications now use a native Swift floating modal (bottom-right) by default, with AppleScript fallback.
-Override mode with `PUMUKI_MACOS_BLOCKED_DIALOG_MODE=auto|swift-floating|applescript`.
+On non-macOS platforms, the same payloads are written to **stderr** by default (visible in the terminal) because there is no native banner API. Set `PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` to silence that path (delivery reports `unsupported-platform` on those OSes). On macOS, set `PUMUKI_NOTIFICATION_STDERR_MIRROR=1` to duplicate **any** notification payload to stderr in addition to the system notification. For **`gate.blocked`** specifically, stderr mirroring is **on by default** when the macOS path reports success (so a failed push/commit still prints a `[pumuki]` block in the terminal even if the banner does not appear); disable only that default with `PUMUKI_DISABLE_GATE_BLOCKED_STDERR_MIRROR=1`. The **blocked modal** (Swift **`NSAlert`** modal dialog / AppleScript) with **Desactivar / Silenciar 30 min / Mantener activas** is **on by default** whenever notifications are enabled and `blockedDialogEnabled` is omitted in `.pumuki/system-notifications.json`. Turn it off with `"blockedDialogEnabled": false` or `PUMUKI_MACOS_BLOCKED_DIALOG=0`. **`gate.blocked`** now emits **both** the Notification Center banner (`osascript`) **and** the interactive modal by default, so consumers (e.g. hooks in other repos) still get a visible banner if the modal cannot attach to a GUI session. To restore the previous “modal only” behaviour and suppress the duplicate banner, set `PUMUKI_MACOS_GATE_BLOCKED_BANNER_DEDUPE=1`. If you see **no** notifications at all: confirm `PUMUKI_DISABLE_SYSTEM_NOTIFICATIONS` is unset, delete or fix `.pumuki/system-notifications.json` (absent file defaults to enabled), and ensure the terminal app is allowed to show notifications in **System Settings → Notifications**.
+Blocked notifications use a **Swift-compiled helper** that shows an **`NSAlert`** (reliable button hit-testing) by default, with AppleScript fallback if `swift` fails.
+Override mode with `PUMUKI_MACOS_BLOCKED_DIALOG_MODE=auto|swift-floating|applescript` (the `swift-floating` name is kept for compatibility; the Swift path is alert-based).
 Custom skills import is available in advanced menu option `33` (writes `/.pumuki/custom-rules.json`).
 Menu-driven audits apply SDD guardrails with the same strict semantics as stage runners (no bypass).
 
@@ -575,6 +611,7 @@ OpenSpec integration behavior:
 - SDD/OpenSpec enforcement invokes the CLI only from **`{repo}/node_modules/.bin/openspec`** (no fallback to a generic `openspec` on `PATH`).
 - `pumuki install` auto-bootstraps OpenSpec (`@fission-ai/openspec`) when missing/incompatible and scaffolds `openspec/` project baseline when absent.
 - `pumuki install --with-mcp` adds adapter/MCP wiring bootstrap and prints MCP health summary on completion.
+- The **`pumuki` package `postinstall`** runs baseline `pumuki install` from the consumer root (hooks + **`.pumuki/adapter.json`** con comandos MCP stdio, **sin** rutas de IDE). MCP wiring is opt-in via `PUMUKI_POSTINSTALL_WITH_MCP=1` or `PUMUKI_POSTINSTALL_MCP_AGENT=repo|cursor|claude|codex`. Repins refrescan ese contrato de forma **independiente de Cursor/CLI/extensión**. Disable MCP wiring en postinstall: `PUMUKI_POSTINSTALL_SKIP_MCP=1`. Escribir también ficheros de IDE en postinstall: `PUMUKI_POSTINSTALL_MCP_AGENT=cursor|claude|codex` (ver `docs/product/INSTALLATION.md`).
 - `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` before hook reinstall.
 
 Safety rule:

package/docs/tracking/plan-curso-pumuki-stack-my-architecture.md

@@ -0,0 +1,118 @@
+# Diseño pedagógico y seguimiento — Curso Pumuki (Stack My Architecture)
+
+Este documento define **qué debe aprender una persona**, **en qué orden**, **cómo se comprueba** y **qué confusiones hay que romper**. El seguimiento de repos y build va **al final**; no sustituye el diseño.
+
+No sustituye el espejo de producto en [`plan-activo-de-trabajo.md`](./plan-activo-de-trabajo.md).
+
+## Leyenda operativa
+
+- ✅ Entregado en repo curso + coherente con USAGE/INSTALLATION
+- 🚧 Única tarea activa (máx. 1)
+- ⏳ Pendiente
+- ⛔ Bloqueado
+
+---
+
+## 1. Para quién es y qué problema resuelve
+
+**Quién:** desarrollador o tech lead que debe **vivir** con hooks, CI y (a veces) agentes; no auditor de slides.
+
+**Problema:** en la práctica mezcla *SDD*, *gate*, *MCP*, *evidencia* y *menú*; cuando algo bloquea no sabe **qué capa** falló ni **qué comando** la inspecciona.
+
+**Éxito del curso:** tras cerrarlo, en un repo real puede (1) nombrar el **stage** y el **scope** de un fallo, (2) leer **`.ai_evidence.json`** y relacionarlo con stderr, (3) distinguir **enforcement** (hooks/CI) de **lectura/agente** (MCP), (4) ejecutar el **flujo SDD mínimo** sin confundirlo con “arreglar reglas”, (5) instalar, actualizar o **retirar** Pumuki sin dejar hooks huérfanos.
+
+- **Cierre local y release gate:** `build-hub.sh --mode strict` + smoke runtime en verde.
+- **Origen en GitHub:** el repo **`stack-my-architecture-hub`** tiene en **`main`** la carpeta estática **`pumuki/`** y el pipeline `build-hub` que la genera (sincronizado con remoto; despliegue a producción con el workflow cuando toque).
+- **Repo Pumuki (ramas):** la documentación del curso en este repositorio está integrada en **`develop`** (**PR #746**, merge `428f10d`). La rama **`main`** del producto va **muy por detrás** de `develop` (del orden de **~600** commits a fecha de integración del plan); promover `develop` → `main` es un **release de producto** aparte, no parte del cierre de este plan formativo.
+- **GitHub Actions:** la org **no** dispone de cuota útil para Actions → el **Hub Production Release Gate** en CI **no** se usa como gate; publicación y comprobaciones **en local** con `./scripts/publish-architecture-stack.sh` en el repo del hub (Vercel CLI + mismos scripts).
+- **Publicación Vercel:** deploy del proyecto `stack-my-architecture-hub` con verificación de rutas contra el alias **`https://stack-my-architecture-hub.vercel.app`** (incluye `/pumuki/` → 200). El script `publish-architecture-stack.sh` infiere la base desde `Aliased:` (o `SMA_PUBLISH_VERIFY_BASE_URL`) y escribe **`.runtime/publish-verify-base.url`** para alinear `post-deploy-checks.sh` con la URL verificada (localmente o cuando Actions vuelva a estar disponible).
+- Si **`https://architecture-stack.vercel.app`** debe exponer el mismo árbol estático que el hub, sincroniza proyecto/CNAME según tu setup (nota emitida por el script al publicar).
+
+Si eso no se cumple, el curso falla aunque el HTML sea bonito.
+
+---
+
+## 2. Modelo mental único (todo el curso orbita aquí)
+
+Una sola frase que el alumno debe poder repetir:
+
+**Hechos del diff/código → reglas efectivas → decisión del gate por stage → registro en evidencia v2.1.**
+
+Todo lo demás (menú, MCP, notificaciones, `doctor`) es **acceso** a ese mismo pipeline o **comodidad**; no es un segundo producto.
+
+---
+
+## 3. Confusiones que el material debe desmontar de forma explícita
+
+Cada unidad del curso debe tener al menos un párrafo “**no confundas**” o un mini escenario:
+
+| Confusión típica | Verdad operativa |
+|------------------|------------------|
+| “Sin MCP no hay Pumuki” | Los **hooks y CI** son el enforcement; MCP es **opcional** para IDE/agente. |
+| “SDD es lo mismo que el gate” | SDD/OpenSpec gobierna el **cambio**; el gate evalúa **código + política + evidencia** en un **scope** concreto. |
+| “`openspec` en el PATH basta” | Pumuki usa OpenSpec **repo-local** (`node_modules/.bin`). |
+| “PRE_COMMIT limpio ⇒ push seguro” | **PRE_PUSH** mira otro **scope** (`upstream..HEAD`). |
+| “El menú es la fuente de verdad” | El menú **orquesta** diagnósticos; la fuente de verdad es **policy + stage + evidencia**. |
+| “Borrar el paquete limpia el repo” | `npm uninstall pumuki` **no** quita hooks/lifecycle; hace falta **`pumuki remove`** / flujo documentado. |
+
+Si el Markdown del curso no nombra estas líneas, el plan pedagógico sigue vacío aunque haya tablas de check.
+
+---
+
+## 4. Secuencia didáctica (orden de primera lectura)
+
+El repo del curso incluye la **columna vertebral en prosa** `00-preparacion/03-recorrido-cero-a-cien-pumuki.md` (0→100 % sin saltos) y el **proyecto guiado** `02-modulos/13-proyecto-guiado-de-la-a-la-z.md` (fases A–M con criterios de hecho). Esta tabla U0–U10 sigue siendo el contrato de **outcomes**; esas piezas son el **relato** y el **laboratorio** que los materializan.
+
+El **mapa completo** (`00-mapa-completo-del-producto.md`) es **referencia** para quien ya perdió el hilo; la **primera pasada** debe seguir esta secuencia para no cargar conceptos antes de tiempo.
+
+| Orden | Unidad | Objetivo observable (el alumno demuestra…) | Actividad mínima en lab | Criterio de dominio |
+|-------|--------|---------------------------------------------|-------------------------|----------------------|
+| U0 | Preparación + versión + lab | Que existe documentación canónica y un repo donde ensayar | Abrir USAGE e INSTALLATION; fijar versión mínima `pumuki` | Explica en una frase dónde miente un “funciona en mi máquina” sin `doctor` |
+| U1 | Contrato + stages + cobertura | Qué pregunta **cada** stage y qué es `unevaluated_rule_ids` | Un `pre-commit` / `pre-push` y leer evidencia | Predice scope antes de ejecutar y acierta al comparar con JSON |
+| U2 | Instalación y primer verde | Postinstall, `bootstrap` vs `install`, `pathExecutionHazard` | `doctor --json` antes/después de un cambio reversible | Usa `alignmentCommand` o workaround sin improvisar |
+| U3 | Ciclo de vida completo | Diferencia `npm uninstall`, `pumuki uninstall`, `pumuki remove`, `update --latest` | Simular retirada en rama de prueba | Lista qué queda en disco tras cada comando |
+| U4 | Evidencia | Dónde se escribe, cuándo **no** se reescribe (PRE_PUSH trackeado), restage PRE_COMMIT | Diff de `.ai_evidence.json` entre stages | Explica un caso “hook modificó archivo” sin pánico |
+| U5 | Menú interactivo | Consumer vs Advanced; 1–4/8/9; matrix; variables UI | Correr `pumuki-framework` y una opción de cada familia | Enlaza opción de menú con **stage** y **scope** equivalentes |
+| U6 | MCP | Evidence vs enterprise; HTTP vs stdio; recibo PRE_WRITE | Levantar o inspeccionar config en `.pumuki/adapter.json` | Explica por qué el gate puede pasar con MCP caído |
+| U7 | SDD/OpenSpec | Flujo diario: `sdd status`, `session`, `validate`; catálogo de códigos | Abrir sesión de cambio y validar un stage | Clasifica un JSON de bloqueo en “falta OpenSpec” vs “falta sesión” |
+| U8 | Notificaciones y watch | macOS vs stderr; `system-notifications.json`; anti-spam de `watch` | Una sesión `watch --once` o documentada | Elige variable correcta para silenciar o espejar |
+| U9 | Perfiles, Governance, monorepo | Cuándo bajar de enterprise; prefijos de scope; parity | (Según perfil del equipo) | Justifica un perfil sin autoboicot |
+| U10 | Cierre | Checklist operativa propia del equipo | Checklist escrita a partir del curso | Puede enseñar el modelo mental §2 a otra persona en 3 minutos |
+
+**Regla:** ninguna fila U1–U10 puede considerarse “hecha” solo con un enlace a USAGE; debe existir **narrativa + comando + actividad + criterio** en el Markdown del curso.
+
+---
+
+## 5. Qué el curso no debe intentar (límites)
+
+- Sustituir el curso **SDD** (OpenSpec, Kanban del cambio) ni el **Governance** (AGENTS, cultura): solo **enganchar** Pumuki a ellos.
+- Sustituir tests de producto, revisión humana ni criterios de negocio.
+- Prometer “cero lectura de USAGE”: USAGE sigue siendo norma; el curso debe **enseñar** lo mismo con **menor fricción**, no duplicar mal.
+
+---
+
+## 6. Estado de entrega en el repo (operativo, subordinado al §4)
+
+| Unidad §4 | Estado en `stack-my-architecture-pumuki` |
+|-----------|-------------------------------------------|
+| U0–U2 | ✅ Base + módulo 2; ciclo de vida **completo** en **08** |
+| U3 | ✅ `02-modulos/08-ciclo-de-vida-install-uninstall-actualizacion.md` |
+| U4 | ✅ `02-modulos/09-evidencia-por-stage-y-ai-evidence-json.md` |
+| U5 | ✅ `02-modulos/10-menu-interactivo-matrix-y-preflight.md` |
+| U6 | ✅ `02-modulos/11-mcp-enforcement-vs-lectura-agente.md` |
+| U7 | ✅ Módulo **04** ampliado (§4.6–4.8 + criterio dominio) |
+| U8 | ✅ `02-modulos/12-notificaciones-macos-stderr-y-watch.md` |
+| U9–U10 | ✅ Revisar checklist **07** frente a criterios §4 en próxima iteración |
+
+| Task | Estado |
+|------|--------|
+| Implementar U3–U8 en `.md` + `FILE_ORDER` + validación | ✅ |
+| CHANGELOG curso + rebuild HTML + sync hub local | ✅ (incl. CSS lectura **0.3.1**) |
+| Push hub + deploy Vercel (ver curso en prod) | 🚧 |
+
+---
+
+## 7. Auditoría técnica (no confundir con evaluación del alumno)
+
+- `python3 scripts/validate-course-structure.py` y `check-links.py` en repo curso.
+- Publicación hub según tu script; URL `/pumuki/` 200.

package/docs/validation/README.md

@@ -14,9 +14,11 @@ Este directorio contiene solo documentación estable de validación y runbooks o
 
 ## Estado de seguimiento
 
-- `docs/validation/` no gobierna backlog.
-- La única fuente viva del tracking interno es `PUMUKI-RESET-MASTER-PLAN.md` en la raíz del repo.
-- `docs/tracking/plan-activo-de-trabajo.md` queda retirado como espejo operativo y solo conserva valor histórico.
+- Única fuente de seguimiento: `docs/tracking/plan-activo-de-trabajo.md`
+
+## GitHub Actions y cuota
+
+Si la organización **no tiene minutos útiles** de Actions, los workflows bajo `.github/workflows/` **no bloquean** el flujo de merge ni sustituyen la evidencia: la barra operativa es **local** — comando único recomendado: **`npm run -s validation:local-merge-bar`** (`typecheck` + `validation:pumuki-surface-smoke` + `npm test`). Complementos habituales: hooks Pumuki, `validation:tracking-single-active`, etc. Alineado con `docs/tracking/plan-activo-de-trabajo.md`.
 
 ## Política de higiene
 
@@ -32,3 +34,4 @@ Este directorio contiene solo documentación estable de validación y runbooks o
 - Higiene hard del worktree propio: `npm run -s validation:self-worktree-hygiene`
 - Suite contractual enterprise: `npm run -s validation:contract-suite:enterprise`
 - Verificación de plan activo único + higiene hard del worktree propio: `npm run -s validation:tracking-single-active`
+- **Smoke de superficie Pumuki** (~29 filas: CLI, `doctor`/`status`, `audit` (varios stages), `watch` (repo + staged), `loop`, `adapter` dry-run repo+codex, `analytics`, `policy` normal+`--strict`, `sdd status`+`validate` por stage, hooks): desde la raíz de **este** repo, `npm run -s smoke:pumuki-surface` (alias: `npm run -s validation:pumuki-surface-smoke`). Tests del resolver y del exit 2 sin `node_modules/pumuki`: `npx --yes tsx@4.21.0 --test scripts/__tests__/pumuki-full-surface-smoke-lib.test.ts scripts/__tests__/pumuki-full-surface-smoke-exit2.test.ts`. Opcional sobre un consumidor con **bins del tree pumuki** (gate en el cwd del consumidor): `PUMUKI_SMOKE_REPO_ROOT=/ruta/abs/al/consumer npm run -s smoke:pumuki-surface`. Para validar **exactamente lo instalado** en `node_modules/pumuki` del consumidor: `PUMUKI_SMOKE_REPO_ROOT=/ruta/abs/al/consumer PUMUKI_SMOKE_BIN_STRATEGY=installed npm run -s smoke:pumuki-surface`, o `PUMUKI_SMOKE_REPO_ROOT=/ruta/abs/al/consumer npm run -s smoke:pumuki-surface-installed`. Ver interpretación de exit codes al final del informe impreso.

package/integrations/config/skillsCustomRules.ts

@@ -49,15 +49,6 @@ export type CompiledImportedSkillsRulesResult = Omit<
   'outputPath'
 >;
 
-export type SkillImportSourceDiagnostic = {
-  skillName: string;
-  canonicalSkillName: string;
-  sourcePath: string;
-  sourceType: 'declared_path' | 'required_skill';
-  issue: 'missing' | 'unreadable';
-  resolution: string;
-};
-
 type VendorSkillManifestEntry = {
   name: string;
   file: string;
@@ -432,57 +423,22 @@ const loadVendorSkillsManifest = (
   return bySkillName;
 };
 
-const buildSkillImportResolution = (sourcePath: string): string => {
-  const normalized = sourcePath.replace(/\\/g, '/');
-  if (normalized.includes('/docs/codex-skills/') || normalized.startsWith('docs/codex-skills/')) {
-    return `Restaura ${sourcePath} o ejecuta ./scripts/sync-codex-skills.sh para resincronizar las skills vendorizadas.`;
-  }
-  if (normalized.includes('/vendor/skills/') || normalized.startsWith('vendor/skills/')) {
-    return `Restaura ${sourcePath} desde vendor/skills o resincroniza las dependencias del repositorio.`;
-  }
-  return `Corrige la ruta declarada o restaura ${sourcePath} para que la skill requerida vuelva a estar disponible.`;
-};
-
-const canReadSkillSourceFile = (sourcePath: string): boolean => {
-  try {
-    readFileSync(sourcePath, 'utf8');
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-export const resolveSkillImportSourcesWithDiagnostics = (params: {
+export const resolveSkillImportSources = (params: {
   repoRoot?: string;
   explicitSources?: ReadonlyArray<string>;
-}): { sourceFiles: string[]; diagnostics: SkillImportSourceDiagnostic[] } => {
+}): string[] => {
   const repoRoot = params.repoRoot ?? process.cwd();
   const resolved = new Map<string, { path: string; priority: number }>();
   const vendoredManifest = loadVendorSkillsManifest(repoRoot);
-  const diagnostics: SkillImportSourceDiagnostic[] = [];
-
-  const registerDiagnostic = (
-    rawPath: string,
-    skillName: string,
-    canonicalSkillName: string,
-    sourceType: SkillImportSourceDiagnostic['sourceType'],
-    issue: SkillImportSourceDiagnostic['issue'],
-  ): void => {
+
+  const pushIfExists = (rawPath: string): void => {
     const normalized = normalizePath({
       repoRoot,
       path: rawPath,
     });
-    diagnostics.push({
-      skillName,
-      canonicalSkillName,
-      sourcePath: normalized,
-      sourceType,
-      issue,
-      resolution: buildSkillImportResolution(normalized),
-    });
-  };
-
-  const pushResolved = (normalized: string): void => {
+    if (!existsSync(normalized)) {
+      return;
+    }
     const skillKey = toCanonicalImportedSkillName(sourceSkillNameFromPath(normalized));
     const priority = isVendoredSkillMarkdownPath(normalized) ? 2 : 1;
     const current = resolved.get(skillKey);
@@ -495,36 +451,13 @@ export const resolveSkillImportSourcesWithDiagnostics = (params: {
     }
   };
 
-  const registerSource = (
-    rawPath: string,
-    skillName: string,
-    canonicalSkillName: string,
-    sourceType: SkillImportSourceDiagnostic['sourceType'],
-  ): void => {
-    const normalized = normalizePath({
-      repoRoot,
-      path: rawPath,
-    });
-    if (!existsSync(normalized)) {
-      registerDiagnostic(rawPath, skillName, canonicalSkillName, sourceType, 'missing');
-      return;
-    }
-    if (!canReadSkillSourceFile(normalized)) {
-      registerDiagnostic(rawPath, skillName, canonicalSkillName, sourceType, 'unreadable');
-      return;
-    }
-    pushResolved(normalized);
-  };
-
   if (params.explicitSources && params.explicitSources.length > 0) {
     for (const source of params.explicitSources) {
-      const normalized = normalizePath({ repoRoot, path: source });
-      registerSource(source, sourceSkillNameFromPath(normalized), toCanonicalImportedSkillName(sourceSkillNameFromPath(normalized)), 'declared_path');
+      pushIfExists(source);
     }
-    return {
-      sourceFiles: [...resolved.values()].map((item) => item.path).sort(),
-      diagnostics,
-    };
+    return [...resolved.values()]
+      .map((item) => item.path)
+      .sort();
   }
 
   for (const profileFile of ['AGENTS.md', 'SKILLS.md']) {
@@ -534,37 +467,23 @@ export const resolveSkillImportSourcesWithDiagnostics = (params: {
     }
     const content = readFileSync(profilePath, 'utf8');
     for (const candidate of extractSkillPathsFromText(content)) {
-      const normalized = normalizePath({ repoRoot, path: candidate });
-      const skillName = sourceSkillNameFromPath(normalized);
-      registerSource(candidate, skillName, toCanonicalImportedSkillName(skillName), 'declared_path');
+      pushIfExists(candidate);
     }
     for (const requiredSkillName of extractRequiredSkillNamesFromText(content)) {
       const canonicalName = toCanonicalImportedSkillName(requiredSkillName);
       const manifestPath = vendoredManifest.get(canonicalName);
       if (manifestPath) {
-        registerSource(manifestPath, requiredSkillName, canonicalName, 'required_skill');
+        pushIfExists(manifestPath);
         continue;
       }
-      const canonicalVendoredPath = `vendor/skills/${canonicalName}/SKILL.md`;
-      const requiredVendoredPath = `vendor/skills/${requiredSkillName}/SKILL.md`;
-      const selectedPath = existsSync(normalizePath({ repoRoot, path: requiredVendoredPath }))
-        ? requiredVendoredPath
-        : canonicalVendoredPath;
-      registerSource(selectedPath, requiredSkillName, canonicalName, 'required_skill');
+      pushIfExists(`vendor/skills/${requiredSkillName}/SKILL.md`);
+      pushIfExists(`vendor/skills/${canonicalName}/SKILL.md`);
     }
   }
 
-  return {
-    sourceFiles: [...resolved.values()].map((item) => item.path).sort(),
-    diagnostics,
-  };
-};
-
-export const resolveSkillImportSources = (params: {
-  repoRoot?: string;
-  explicitSources?: ReadonlyArray<string>;
-}): string[] => {
-  return resolveSkillImportSourcesWithDiagnostics(params).sourceFiles;
+  return [...resolved.values()]
+    .map((item) => item.path)
+    .sort();
 };
 
 export const compileImportedSkillsRules = (params: {