pumuki 6.3.71 → 6.3.73

package/README.md

@@ -12,6 +12,12 @@ Pumuki gives engineering teams one deterministic execution model across local de
 
 `Facts -> Rules -> Gate -> .ai_evidence.json (v2.1)`
 
+## Qué NO es Pumuki
+
+- **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**.
+
 ## Who This README Is For
 
 | Profile | Use this path first |
@@ -20,6 +26,32 @@ Pumuki gives engineering teams one deterministic execution model across local de
 | Framework maintainers (this repo) | [Framework Maintainer Flow](#framework-maintainer-flow-this-repo) |
 | Platform/architecture owners | [Enterprise Operations Baseline](#enterprise-operations-baseline) |
 
+## Rutas de adopción
+
+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.
+
+| 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. |
+| **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). |
+
+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).
+
+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).
+
+## Comandos esenciales
+
+Cinco entradas que cubren el 80 % del día a día en un consumidor; el detalle está en los enlaces.
+
+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.
+
+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)
 
 Prerequisites:

package/VERSION

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

package/docs/README.md

@@ -4,6 +4,8 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 
 ## Si buscas algo concreto
 
+- 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:
   - `README.md`
   - `docs/product/INSTALLATION.md`
@@ -35,6 +37,8 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 
 - Quiero saber en qué estamos ahora:
   - `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
 
@@ -62,8 +66,9 @@ Mapa corto y humano de la documentación oficial de Pumuki.
 
 - `docs/tracking/`
   - Seguimiento permitido y solo el imprescindible.
-  - Unica fuente de verdad: `docs/tracking/plan-activo-de-trabajo.md`
-  - Regla hard: solo puede existir una tarea `🚧` en el plan activo.
+  - Espejo operativo de producto y consumidores: `docs/tracking/plan-activo-de-trabajo.md` (unica fuente de verdad para ese ambito).
+  - 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,6 +6,24 @@ 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`; `npm publish` cuando el tarball incluya lo anterior; luego `pumuki doctor --json` + repin en consumidores (p. ej. RuralGO).
+
 ### 2026-04-06 (v6.3.71)
 
 - **Evidencia v2.1**: bloque `operational_hints` (`requires_second_pass`, resumen operativo, desglose por severidad de reglas). Alineado con PRE_COMMIT solo-docs + evidencia trackeada (INC-069) cuando no se re-stagea el JSON automáticamente.

package/docs/product/USAGE.md

@@ -14,6 +14,11 @@ Production operations baseline (SLA/SLO, incident response and alerting):
 Visual walkthrough for menu Option 1 captures:
 - `docs/operations/framework-menu-consumer-walkthrough.md`
 
+Stack My Architecture (optional training hub; includes the dedicated Pumuki course):
+
+- 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`
+
 ## Prerequisites
 
 - Node.js `>=18`
@@ -72,6 +77,8 @@ Platform activation:
 
 Pumuki enforces OpenSpec policy/session before allowing normal gate execution.
 
+OpenSpec CLI resolution is **repo-local only**: Pumuki runs `openspec` from **`node_modules/.bin`** in the repository under check. A binary named `openspec` elsewhere on your **`PATH`** (global install, another tool) is **not** used. Add **`@fission-ai/openspec`** to the consumer project (for example via `pumuki install` / `bootstrap`) so laptops and CI behave the same; otherwise you may see **`OPENSPEC_MISSING`** even when `openspec --version` succeeds in an interactive shell.
+
 Minimal daily flow:
 
 ```bash
@@ -565,6 +572,7 @@ npx --yes tsx@4.21.0 scripts/reconcile-consumer-backlog-issues.ts \
 
 OpenSpec integration behavior:
 - `pumuki bootstrap --enterprise --agent=<name>` orquesta `install + adapter wiring + doctor --deep` en un solo paso.
+- 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.
 - `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` before hook reinstall.
@@ -806,6 +814,8 @@ npx --yes pumuki sdd status
 npx --yes pumuki sdd validate --stage=PRE_COMMIT
 ```
 
+If the gate reports **`OPENSPEC_MISSING`** but `openspec --version` works in the terminal, you are likely using a **global** OpenSpec install. Pumuki does not use that path; install the package in the repo (`npm install`, `pumuki install`, or `pumuki bootstrap`) so `node_modules/.bin/openspec` exists.
+
 Open or refresh session if needed:
 
 ```bash

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

@@ -0,0 +1,62 @@
+# Seguimiento — Curso Pumuki (Stack My Architecture)
+
+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).
+
+## Leyenda
+
+- ✅ Cerrado
+- 🚧 En construccion (maximo 1)
+- ⏳ Pendiente
+- ⛔ Bloqueado
+
+## 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/GitService.ts

@@ -9,6 +9,7 @@ export { parseNameStatus } from './gitDiffUtils';
 export interface IGitService {
   runGit(args: ReadonlyArray<string>, cwd?: string): string;
   getStagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact>;
+  getUnstagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact>;
   getRepoFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact>;
   getRepoAndStagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact>;
   getStagedAndUnstagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact>;
@@ -44,6 +45,30 @@ export class GitService implements IGitService {
     );
   }
 
+  getUnstagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact> {
+    const nameStatus = this.runGit(['diff', '--name-status']);
+    const changes = parseNameStatus(nameStatus).filter((change) =>
+      hasAllowedExtension(change.path, extensions)
+    );
+    const untrackedPaths = this.runGit(['ls-files', '--others', '--exclude-standard'])
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .filter((path) => hasAllowedExtension(path, extensions));
+    const unstagedPaths = new Set(changes.map((change) => change.path));
+    const untrackedChanges = untrackedPaths
+      .filter((path) => !unstagedPaths.has(path))
+      .map((path) => ({
+        path,
+        changeType: 'added' as const,
+      }));
+    const mergedChanges = [...changes, ...untrackedChanges];
+    const repoRoot = this.resolveRepoRoot();
+    return buildFactsFromChanges(mergedChanges, 'git:unstaged', (filePath) =>
+      this.readWorkingTreeFile(repoRoot, filePath)
+    );
+  }
+
   getRepoFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact> {
     const trackedFiles = this.runGit(['ls-files'])
       .split('\n')

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

@@ -27,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>();

package/integrations/git/runPlatformGateOutput.ts

@@ -1,27 +1,5 @@
 import type { Finding } from '../../core/gate/Finding';
-
-const BLOCK_NEXT_ACTION_BY_CODE: Readonly<Record<string, string>> = {
-  SDD_SESSION_MISSING:
-    'npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>',
-  SDD_SESSION_INVALID:
-    'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90',
-  PRE_PUSH_UPSTREAM_MISSING:
-    'git push --set-upstream origin <branch>',
-  PRE_PUSH_UPSTREAM_MISALIGNED:
-    'git branch --unset-upstream && git push --set-upstream origin <branch>',
-  EVIDENCE_STALE:
-    'npx --yes --package pumuki@latest pumuki-pre-commit',
-  EVIDENCE_BRANCH_MISMATCH:
-    'npx --yes --package pumuki@latest pumuki-pre-commit',
-  GIT_ATOMICITY_TOO_MANY_FILES:
-    'git restore --staged . && separa cambios en commits más pequeños',
-  GIT_ATOMICITY_TOO_MANY_SCOPES:
-    'Revisa scope_files del bloqueo y aplica: git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"',
-  ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH:
-    'Reconcilia policy/skills y reintenta PRE_COMMIT: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki-pre-commit',
-  SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS:
-    'Aplica refactor incremental: extrae 1 componente/hook por commit y vuelve a ejecutar PRE_COMMIT.',
-};
+import { resolveGovernanceCatalogAction } from '../gate/governanceActionCatalog';
 
 const severityWeight = (severity: string): number => {
   switch (severity.toUpperCase()) {
@@ -94,18 +72,49 @@ const formatFinding = (finding: Finding): string => {
   return `[${severity}] ${finding.ruleId}: ${finding.message} -> ${location}`;
 };
 
-export const printGateFindings = (findings: ReadonlyArray<Finding>): void => {
+const resolveAtomicityFallback = (code: string): string | null => {
+  switch (code) {
+    case 'GIT_ATOMICITY_TOO_MANY_FILES':
+      return 'git restore --staged . && separa cambios en commits más pequeños';
+    case 'GIT_ATOMICITY_TOO_MANY_SCOPES':
+      return 'Revisa scope_files del bloqueo y aplica: git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"';
+    default:
+      return null;
+  }
+};
+
+export const printGateFindings = (
+  findings: ReadonlyArray<Finding>,
+  params?: { stage?: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI' }
+): void => {
   if (findings.length === 0) {
     return;
   }
   const primary = resolvePrimaryFinding(findings);
-  const nextAction =
-    BLOCK_NEXT_ACTION_BY_CODE[primary.code]
-    ?? 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.';
+  const action = resolveGovernanceCatalogAction({
+    code: primary.code,
+    stage: params?.stage ?? 'PRE_COMMIT',
+    fallback: {
+      reason_code: primary.code,
+      instruction: 'Corrige el bloqueante primario y vuelve a ejecutar la validación del stage actual.',
+      next_action: {
+        kind: 'info',
+        message:
+          resolveAtomicityFallback(primary.code)
+          ?? 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.',
+      },
+    },
+  });
+  const nextAction = action.next_action.command ?? action.next_action.message;
   process.stdout.write(
     `[pumuki][block-summary] primary=${primary.code} severity=${primary.severity.toUpperCase()} rule=${primary.ruleId}\n`
   );
+  process.stdout.write(`[pumuki][block-summary] reason_code=${action.reason_code}\n`);
+  process.stdout.write(`[pumuki][block-summary] instruction=${action.instruction}\n`);
   process.stdout.write(`[pumuki][block-summary] next_action=${nextAction}\n`);
+  if (action.next_action.command) {
+    process.stdout.write(`[pumuki][block-summary] command=${action.next_action.command}\n`);
+  }
   for (const finding of findings) {
     process.stdout.write(`${formatFinding(finding)}\n`);
   }

package/integrations/lifecycle/adapter.templates.json

@@ -2,6 +2,7 @@
   "codex": [
     {
       "path": ".pumuki/adapter.json",
+      "mode": "json-merge",
       "payload": {
         "hooks": {
           "pre_write": {
@@ -31,6 +32,7 @@
   "repo": [
     {
       "path": ".pumuki/adapter.json",
+      "mode": "json-merge",
       "payload": {
         "hooks": {
           "pre_write": {
@@ -143,6 +145,7 @@
     },
     {
       "path": ".pumuki/adapter.json",
+      "mode": "json-merge",
       "payload": {
         "hooks": {
           "pre_write": {