pumuki 6.3.72 → 6.3.73

package/CHANGELOG.md

@@ -6,14 +6,34 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [6.3.73] - 2026-04-14
+
+### Added
+
+- **Consola S1 de governance**: `status`, `doctor`, menú consumer, hooks y MCP empiezan a hablar el mismo vocabulario operativo con `governance truth`, `reason_code`, `instruction` y `next_action`, apoyados en `integrations/lifecycle/governanceObservationSnapshot.ts`, `integrations/lifecycle/governanceNextAction.ts` y `integrations/gate/governanceActionCatalog.ts`.
+- **Paquete ejecutable de evidencia RuralGo**: nuevo script `validation:ruralgo-s1-evidence-pack` para generar un paquete determinista de comandos shell + capturas MCP orientado a validar `PUMUKI-INC-071/073/076` en el consumer real.
+- **Lifecycle audit**: `integrations/lifecycle/audit.ts` y el wiring de CLI vuelven a formar parte de la línea release para no perder la superficie útil ya publicada en `6.3.72`.
+- **Full surface smoke / consumer postinstall helpers**: se preservan `scripts/pumuki-full-surface-smoke.ts`, `scripts/pumuki-smoke-installed-wrapper.cjs` y `scripts/consumer-postinstall-resolve-args.cjs` para mantener la barra local y el contrato de instalación del consumidor.
+
+### Changed
+
+- **PRE_WRITE / hooks / MCP**: el contrato canónico de governance converge en torno al mismo catálogo compartido; hooks muestran `reason_code`, `instruction` y `next_action`, y MCP expone también `reason_code` + `next_action` en `pre_flight_check`.
+- **Evidence pack con semver exacta**: cuando el paquete se genera con una versión publicada, el comando `PRE_WRITE` queda fijado a esa semver; solo degrada a `pumuki@latest` en contextos locales o no publicados.
+- **Línea release saneada**: `6.3.73` conserva el mínimo funcional ya publicado en `6.3.72` (audit lifecycle, postinstall resolver, platform detection y smoke de superficie) y añade encima la Slice S1 de governance.
+
 ## [6.3.72] - 2026-04-11
 
 ### Fixed
 
+- **Tests `cli` (macOS):** la suite `integrations/lifecycle/__tests__/cli.test.ts` activaba **`emitGateBlockedNotification`** real en escenarios PRE_WRITE **strict** (p. ej. `OPENSPEC_MISSING`), lo que podía **bloquear** `npm test` indefinidamente al abrir notificación/diálogo del sistema. Los tests fijan **`PUMUKI_DISABLE_SYSTEM_NOTIFICATIONS=1`** en `beforeEach` y restauran el env en `afterEach` (misma variable que el producto ya documenta para desactivar notificaciones).
 - **macOS notificaciones en `gate.blocked`**: por defecto vuelve a mostrarse el **banner** de Notification Center además del modal interactivo cuando el modal está activo. Antes, si el modal (Swift/AppleScript) no llegaba a mostrarse desde un hook en un repo consumidor, podía no verse **ninguna** notificación. Opt-in al comportamiento previo (solo modal, sin banner duplicado): `PUMUKI_MACOS_GATE_BLOCKED_BANNER_DEDUPE=1`.
+- **Consumer repin + MCP (IDE-agnóstico)**: el `postinstall` del paquete ejecuta **`pumuki install --with-mcp --agent=repo`** por defecto, actualizando **`.pumuki/adapter.json`** (hooks + comandos MCP stdio) sin depender de Cursor ni de ningún IDE. La plantilla `repo` usa **`json-merge`** para no pisar claves extra del consumidor. Opt-out: `PUMUKI_POSTINSTALL_SKIP_MCP=1`. Opt-in a ficheros de IDE en postinstall: `PUMUKI_POSTINSTALL_MCP_AGENT=cursor|claude|codex`.
+- **macOS diálogo `gate.blocked` (Swift)**: el helper deja de usar un `NSPanel` flotante personalizado y pasa a **`NSAlert.runModal()`**, de modo que **Desactivar / Silenciar 30 min / Mantener activas** respondan de forma fiable a clics y teclado (el panel flotante podía no entregar eventos según foco de otras apps, p. ej. el IDE).
 
 ### Added
 
+- **Smoke de superficie CLI**: `npm run smoke:pumuki-surface` (~29 invocaciones) y `smoke:pumuki-surface-installed` con `PUMUKI_SMOKE_REPO_ROOT` + `PUMUKI_SMOKE_BIN_STRATEGY=installed` para validar el bin bajo `node_modules/pumuki` del consumidor. Ver `docs/validation/README.md`.
+- **Barra local sin GitHub Actions**: `npm run validation:local-merge-bar` (`typecheck` + smoke + `npm test`) como sustituto operativo cuando la org no tiene cuota útil de Actions.
 - **Tarball npm**: el paquete publicado incluye también `AGENTS.md`, `CHANGELOG.md` y `docs/tracking/plan-curso-pumuki-stack-my-architecture.md` (listados en `package.json` → `files`), de modo que la misma versión en **npm** / **jsDelivr** / `node_modules` expone contrato de agentes, historial de release y el plan formativo del curso Pumuki sin depender solo de GitHub.
 - **Menú consumer (`npm run framework:menu`)**: opciones `11` (solo **staged**), `12` (solo **unstaged**: `git diff` + untracked), `13` (**staged + unstaged** con política **PRE_COMMIT** sobre el working tree), `14` (**todo el repo trackeado** sin preflight). Ejecutan el motor de gate **sin preflight** consumer. Nuevo alcance de hechos `unstaged` y `GitService.getUnstagedFacts`.
 - **Vista “classic” en consola**: segundo panel tras el resumen consumer con severidades coloreadas (enterprise + legacy), hasta 45 hallazgos ordenados, filas **platform** si existen en la evidencia, y nota sobre heurística `Other`. Variable `PUMUKI_MENU_VINTAGE_REPORT=0` para desactivar.

package/VERSION

@@ -1 +1 @@
-v6.3.64
+v6.3.73

package/docs/README.md

@@ -67,7 +67,7 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 - `docs/tracking/`
   - 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).
+  - Iniciativa formativa (curso Pumuki en Stack My Architecture): `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

@@ -6,12 +6,23 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 ## 2026-04 (CLI stability and macOS notifications)
 
+### 2026-04-14 (v6.3.73)
+
+- **S1 governance console**: `status`, `doctor`, menú consumer, hooks y MCP comparten ya la misma semántica de governance (`governance truth`, `reason_code`, `instruction`, `next_action`).
+- **RuralGo evidence pack**: nuevo `npm run validation:ruralgo-s1-evidence-pack -- --consumer-root <repo> --package-version <semver>` para preparar la validación real de `PUMUKI-INC-071/073/076`.
+- **Sin regresión de 6.3.72**: esta release preserva `lifecycle audit`, `consumer postinstall resolve args`, `detectPlatforms` y `full surface smoke`, en vez de volver a una base `6.3.71`.
+- **Rollout**: publicar `pumuki@6.3.73`, repinear primero RuralGo y ejecutar el evidence pack con la semver publicada antes de mover ningún `INC` a `FIXED`.
+
 ### 2026-04-11 (v6.3.72)
 
 - **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`; `pumuki doctor --json` + repin en consumidores (p. ej. RuralGO).
+- **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)
 

package/docs/product/USAGE.md

@@ -130,10 +130,7 @@ 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 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.
+- `1/2/3/4` are the canonical read-only gate flows
 - `8` exports the same evidence snapshot in markdown form
 - `5/6/7/9` remain available only as `Legacy Read-Only Diagnostics`
 
@@ -252,7 +249,7 @@ 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`. **`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**.
+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`.
 Custom skills import is available in advanced menu option `33` (writes `/.pumuki/custom-rules.json`).

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

@@ -1,111 +1,62 @@
-# Diseño pedagógico y seguimiento — Curso Pumuki (Stack My Architecture)
+# 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.
+Iniciativa formativa: quinto curso del ecosistema Stack My Architecture. **No** sustituye el espejo operativo de producto en [`plan-activo-de-trabajo.md`](./plan-activo-de-trabajo.md).
 
-No sustituye el espejo de producto en [`plan-activo-de-trabajo.md`](./plan-activo-de-trabajo.md).
+## Leyenda
 
-## Leyenda operativa
-
-- ✅ Entregado en repo curso + coherente con USAGE/INSTALLATION
-- 🚧 Única tarea activa (máx. 1)
+- ✅ Cerrado
+- 🚧 En construccion (maximo 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.
-
-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.
+## Regla de uso
+
+- Solo puede existir **una** tarea `🚧` a la vez en este documento.
+- Actualizar estados al cerrar fases o al desbloquear dependencias.
+- Repos objetivo: `stack-my-architecture-pumuki` (curso), `stack-my-architecture-hub` (publicación), enlaces en `stack-my-architecture-governance` y `stack-my-architecture-SDD`.
+- Producto de referencia: repo `ast-intelligence-hooks` (paquete npm `pumuki`). Documentación canónica: `README.md`, `docs/product/USAGE.md`, `docs/product/INSTALLATION.md`.
+
+## Contexto
+
+- **Objetivo:** curso dedicado a Pumuki como capa de enforcement (`Facts → Rules → Gate → evidencia v2.1`) en repos reales, sin re-enseñar OpenSpec ni ADR (remite a cursos SDD y Governance).
+- **`courseId` propuesto:** `stack-my-architecture-pumuki` (alinear con hub y progress sync).
+- **Versión mínima `pumuki` (MVP):** `>= 6.3.71` (ajustar al publicar el curso si hay release posterior).
+- **Lab de práctica:** variante o fork de **GovernanceKit** (Governance) o **HelpdeskSDD** (SDD); documentado en `00-preparacion/02-lab-governancekit-helpdesksdd.md` del repo del curso.
+
+## Estado actual
+
+- **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).
+
+## Prioridad ordenada (fases y tareas)
+
+| Fase | Task | Estado | Notas |
+|------|------|--------|--------|
+| 0 | Crear repo `stack-my-architecture-pumuki` + README + estructura carpetas | ✅ | Repo bajo `stack-my-architecture/stack-my-architecture-pumuki` |
+| 0 | Definir `courseId` y versión mínima `pumuki` | ✅ | `stack-my-architecture-pumuki`, `>= 6.3.71` |
+| 0 | Elegir proyecto lab (GovernanceKit vs HelpdeskSDD) | ✅ | Documentado en preparación del curso |
+| 1 | Redactar roadmap semanal/módulos (`01-roadmap/`) | ✅ | |
+| 1 | Módulos 1–7 MVP (lecciones + enlaces USAGE/README Pumuki) | ✅ | `02-modulos/` + referencias npm/docs producto |
+| 2 | Integración hub: ruta `/pumuki` + `build-hub.sh` + launcher | ✅ | `stack-hub --course pumuki`, assets desde ios parcheados |
+| 2 | Assistant `courseId` + smoke | ✅ | `_hub-platform.js`, `hub-app.js`, README hub + ejemplo curl |
+| 3 | Enlaces desde Governance y SDD | ✅ | Semana 8 checkpoint + SDD semana 8 |
+| 3 | (Opcional) Anexo iOS/Android Arquitecto/Maestría | ✅ | `00-core-mobile/04-calidad-pr-ready.md` iOS y Android |
+| 4 | Scripts validación curso + primera publicación | ✅ | Curso: validate + check-links; hub: publish strict + `/pumuki/` 200 en alias hub |
+
+## Criterios de cierre por fase
+
+- **Fase 0:** repo clonable, README con prerequisitos y convenciones, scripts mínimos ejecutables.
+- **Fase 1:** siete módulos enlazados a docs oficiales Pumuki; roadmap con orden de lectura.
+- **Fase 2:** `build-hub` genera ruta servible; `stack-hub --course pumuki` documentado.
+- **Fase 3:** enlaces mergeados en repos Governance y SDD (y opcional iOS/Android).
+- **Fase 4:** checklist publicación + versión `pumuki` fijada en lecciones y CHANGELOG del curso.
+
+## Auditoría y release (Fase 4)
+
+- Ejecutar en el repo del curso: `scripts/validate-course-structure.py`, `scripts/check-links.py`.
+- Publicación hub: modo `strict` en `Hub Production Release Gate`; verificación de rutas incluye `/pumuki/` en `publish-architecture-stack.sh`.
+- Tras cada release npm relevante de Pumuki, revisar versión mínima en `00-preparacion/` y en este plan.

package/integrations/gate/governanceActionCatalog.ts

@@ -0,0 +1,230 @@
+import type { AiGateStage } from './evaluateAiGate';
+
+export type GovernanceCatalogNextAction = {
+  kind: 'info' | 'run_command';
+  message: string;
+  command?: string;
+};
+
+export type GovernanceCatalogAction = {
+  reason_code: string;
+  instruction: string;
+  next_action: GovernanceCatalogNextAction;
+};
+
+const PRE_WRITE_VALIDATE_COMMAND =
+  'npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json';
+
+export const buildGovernanceValidateCommand = (stage: AiGateStage): string =>
+  PRE_WRITE_VALIDATE_COMMAND.replace('PRE_WRITE', stage);
+
+export const buildGovernancePolicyReconcileCommand = (stage: AiGateStage): string =>
+  `npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && ${buildGovernanceValidateCommand(stage)}`;
+
+const buildFallbackAction = (code: string): GovernanceCatalogAction => ({
+  reason_code: code,
+  instruction: 'Corrige el bloqueante primario y vuelve a ejecutar la validación del stage actual.',
+  next_action: {
+    kind: 'info',
+    message: 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.',
+  },
+});
+
+export const resolveGovernanceCatalogAction = (params: {
+  code: string;
+  stage?: AiGateStage;
+  fallback?: GovernanceCatalogAction;
+}): GovernanceCatalogAction => {
+  const stage = params.stage ?? 'PRE_WRITE';
+  const validateCommand = buildGovernanceValidateCommand(stage);
+  switch (params.code) {
+    case 'READY':
+      return {
+        reason_code: 'READY',
+        instruction: 'Puedes continuar con la siguiente slice mínima y volver a validar al cerrar.',
+        next_action: {
+          kind: 'info',
+          message: 'Gate en verde. Continúa con la implementación.',
+        },
+      };
+    case 'EVIDENCE_INVALID_OR_CHAIN':
+      return {
+        reason_code: 'EVIDENCE_INVALID_OR_CHAIN',
+        instruction: 'Regenera la evidencia canónica antes de continuar.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Regenera o corrige la evidencia canónica (.ai_evidence.json) y vuelve a validar governance.',
+          command: validateCommand,
+        },
+      };
+    case 'AI_GATE_BLOCKED':
+      return {
+        reason_code: 'AI_GATE_BLOCKED',
+        instruction: 'Corrige primero el bloqueo principal del gate antes de continuar.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Revalida el stage tras corregir la evidencia y el bloqueo principal.',
+          command: validateCommand,
+        },
+      };
+    case 'SDD_SESSION_MISSING':
+      return {
+        reason_code: 'SDD_SESSION_MISSING',
+        instruction: 'Abre una sesión SDD válida antes de seguir trabajando.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Abre la sesión SDD del cambio activo y vuelve a validar.',
+          command: 'npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>',
+        },
+      };
+    case 'SDD_SESSION_INVALID':
+    case 'SDD_SESSION_INVALID_OR_EXPIRED':
+      return {
+        reason_code: 'SDD_SESSION_INVALID_OR_EXPIRED',
+        instruction: 'Refresca o reabre la sesión SDD antes de seguir trabajando.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Refresca la sesión SDD y vuelve a validar governance.',
+          command: 'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90',
+        },
+      };
+    case 'PRE_PUSH_UPSTREAM_MISSING':
+      return {
+        reason_code: 'PRE_PUSH_UPSTREAM_MISSING',
+        instruction: 'Configura el upstream remoto antes de continuar con PRE_PUSH.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Configura tracking remoto para la rama actual.',
+          command: 'git push --set-upstream origin <branch>',
+        },
+      };
+    case 'PRE_PUSH_UPSTREAM_MISALIGNED':
+      return {
+        reason_code: 'PRE_PUSH_UPSTREAM_MISALIGNED',
+        instruction: 'Alinea el upstream remoto con la rama actual antes de continuar.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Reconfigura el upstream remoto de la rama actual.',
+          command: 'git branch --unset-upstream && git push --set-upstream origin <branch>',
+        },
+      };
+    case 'GITFLOW_PROTECTED_BRANCH':
+    case 'GITFLOW_PROTECTED_BRANCH_CONTEXT':
+      return {
+        reason_code: 'GITFLOW_PROTECTED_BRANCH_CONTEXT',
+        instruction: 'Sal de la rama protegida y mueve el trabajo a feature/* o refactor/*.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Crea una rama válida de trabajo antes de seguir.',
+          command: 'git checkout -b feature/<descripcion-kebab-case>',
+        },
+      };
+    case 'POLICY_STAGE_NOT_STRICT':
+      return {
+        reason_code: 'POLICY_STAGE_NOT_STRICT',
+        instruction: 'Reconcilia policy/skills en modo estricto antes de seguir.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Converge policy-as-code y revalida el stage actual.',
+          command: buildGovernancePolicyReconcileCommand(stage),
+        },
+      };
+    case 'SKILLS_CONTRACT_SURFACE_INCOMPLETE':
+    case 'EVIDENCE_SKILLS_CONTRACT_INCOMPLETE':
+      return {
+        reason_code: 'SKILLS_CONTRACT_SURFACE_INCOMPLETE',
+        instruction: 'Materializa el lock/sources de skills antes de dar governance efectiva.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Reconcilia policy/skills y vuelve a validar governance.',
+          command: buildGovernancePolicyReconcileCommand(stage),
+        },
+      };
+    case 'ADAPTER_WIRING_MISSING':
+      return {
+        reason_code: 'ADAPTER_WIRING_MISSING',
+        instruction: 'Instala el adaptador canónico si quieres wiring explícito de IDE/MCP.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Genera `.pumuki/adapter.json` desde la instalación canónica.',
+          command: 'npx --yes --package pumuki@latest pumuki install --with-mcp',
+        },
+      };
+    case 'EVIDENCE_STALE':
+    case 'EVIDENCE_BRANCH_MISMATCH':
+    case 'EVIDENCE_SNAPSHOT_WARN':
+      return {
+        reason_code: params.code === 'EVIDENCE_SNAPSHOT_WARN' ? 'EVIDENCE_SNAPSHOT_WARN' : 'EVIDENCE_STALE',
+        instruction: 'Refresca evidencia y revisa hallazgos WARN antes de continuar.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Revalida el stage actual y revisa findings WARN.',
+          command: validateCommand,
+        },
+      };
+    case 'ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH':
+    case 'EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES':
+      return {
+        reason_code: 'EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES',
+        instruction: 'Reconcilia policy/skills en modo estricto y revalida el stage actual.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Converge policy-as-code y vuelve a validar cobertura de active_rule_ids para reglas activas.',
+          command: buildGovernancePolicyReconcileCommand(stage),
+        },
+      };
+    case 'EVIDENCE_PLATFORM_SKILLS_SCOPE_INCOMPLETE':
+    case 'EVIDENCE_PLATFORM_SKILLS_BUNDLES_MISSING':
+      return {
+        reason_code: params.code,
+        instruction: 'Completa cobertura de skills por plataforma y vuelve a validar.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Completa bundles/prefijos de skills requeridos y revalida el stage actual.',
+          command: validateCommand,
+        },
+      };
+    case 'EVIDENCE_PLATFORM_CRITICAL_SKILLS_RULES_MISSING':
+    case 'EVIDENCE_CROSS_PLATFORM_CRITICAL_ENFORCEMENT_INCOMPLETE':
+      return {
+        reason_code: params.code,
+        instruction: 'Reconcilia policy/skills en modo estricto para enforcement crítico y revalida.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Materializa reglas críticas de plataforma y vuelve a validar el stage actual.',
+          command: buildGovernancePolicyReconcileCommand(stage),
+        },
+      };
+    case 'EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT':
+    case 'EVIDENCE_PREWRITE_WORKTREE_WARN':
+      return {
+        reason_code: params.code,
+        instruction: 'Particiona el worktree en slices atómicos antes de continuar.',
+        next_action: {
+          kind: 'run_command',
+          message: 'Reduce el worktree pendiente y revalida el stage actual.',
+          command: `git status --short && git add -p && ${validateCommand}`,
+        },
+      };
+    case 'SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS':
+      return {
+        reason_code: 'SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS',
+        instruction: 'Aplica refactor incremental por componente/hook y vuelve a validar.',
+        next_action: {
+          kind: 'info',
+          message: 'Aplica refactor incremental: extrae 1 componente/hook por commit y vuelve a ejecutar el gate.',
+        },
+      };
+    case 'GOVERNANCE_ATTENTION':
+      return {
+        reason_code: 'GOVERNANCE_ATTENTION',
+        instruction: 'Revisa governance truth y corrige el primer hueco del contrato antes de continuar.',
+        next_action: {
+          kind: 'info',
+          message: 'Revisa governance truth, corrige el primer gap visible y vuelve a validar.',
+        },
+      };
+    default:
+      return params.fallback ?? buildFallbackAction(params.code);
+  }
+};

package/integrations/git/runPlatformGate.ts

@@ -1372,7 +1372,15 @@ export async function runPlatformGate(params: {
 
   if (gateOutcome === 'BLOCK') {
     if (params.silent !== true) {
-    dependencies.printGateFindings(findingsWithWaiver);
+      const renderStage =
+        params.policy.stage === 'PRE_PUSH'
+          ? 'PRE_PUSH'
+          : params.policy.stage === 'CI'
+            ? 'CI'
+            : 'PRE_COMMIT';
+      dependencies.printGateFindings(findingsWithWaiver, {
+        stage: renderStage,
+      });
     }
     return 1;
   }

package/integrations/git/runPlatformGateFacts.ts

@@ -19,10 +19,6 @@ export type GateScope =
     kind: 'workingTree';
     extensions?: string[];
   }
-  | {
-    kind: 'unstaged';
-    extensions?: string[];
-  }
   | {
     kind: 'range';
     fromRef: string;
@@ -31,6 +27,7 @@ export type GateScope =
   };
 
 const DEFAULT_EXTENSIONS = ['.swift', '.ts', '.tsx', '.js', '.jsx', '.kt', '.kts'];
+export const DEFAULT_FACT_FILE_EXTENSIONS = DEFAULT_EXTENSIONS;
 
 export const countScannedFilesFromFacts = (facts: ReadonlyArray<Fact>): number => {
   const contentPaths = new Set<string>();
@@ -70,9 +67,6 @@ export const resolveFactsForGateScope = async (params: {
   if (params.scope.kind === 'workingTree') {
     return params.git.getStagedAndUnstagedFacts(extensions);
   }
-  if (params.scope.kind === 'unstaged') {
-    return params.git.getUnstagedFacts(extensions);
-  }
 
   return getFactsForCommitRange({
     fromRef: params.scope.fromRef,