pumuki 6.3.70 → 6.3.72

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/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).
+  - 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

@@ -6,6 +6,21 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 ## 2026-04 (CLI stability and macOS notifications)
 
+### 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`.
+- **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).
+
+### 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.
+- **Monorepo**: `PUMUKI_GATE_SCOPE_PATH_PREFIXES` acota el primer alcance de hechos por prefijos de ruta.
+- **Paridad CI/local**: `pumuki doctor --parity` y fichero opcional `.pumuki/ci-parity-expected.json` (fallo con exit 1 si hay drift respecto al esperado).
+- **MCP y hooks**: mismas pistas de remediación por código de violación vía catálogo compartido.
+- **Rollout**: `pumuki@6.3.71`; repin en consumidores cuando se publique npm; validar hooks y `doctor --parity` si fijáis expectativas de CI.
+
 ### 2026-04-06 (v6.3.70)
 
 - **Consumidores con pre-commit en pre-push**: con `.ai_evidence.json` **versionado**, `PRE_PUSH` en **ALLOW/WARN** omite persistir en disco para no ensuciar el árbol tras el gate; variable `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1` si necesitas el snapshot `PRE_PUSH` en fichero trackeado (puede exigir flujo de commit explícito).

package/docs/product/CONFIGURATION.md

@@ -317,6 +317,18 @@ Environment variables:
 - `PUMUKI_PREWRITE_WORKTREE_WARN_THRESHOLD` (default: `12`)
 - `PUMUKI_PREWRITE_WORKTREE_BLOCK_THRESHOLD` (default: `24`)
 
+## Alcance del gate por prefijos (monorepos)
+
+- `PUMUKI_GATE_SCOPE_PATH_PREFIXES`: prefijos de ruta separados por **coma** o **punto y coma** (p. ej. `apps/backend,apps/web-app`). Se normalizan barras invertidas a `/`. El **primer** conjunto de hechos del alcance del stage (p. ej. staged o rango de commits) se filtra a rutas bajo esos prefijos. Hechos sin ruta de archivo reconocible (p. ej. algunas dependencias) se conservan para no romper reglas transversales.
+
+## Paridad local vs CI (`pumuki doctor`)
+
+- Fichero opcional **`.pumuki/ci-parity-expected.json`** (commit en el repo consumer): JSON mínimo con los campos que quieras fijar, p. ej. `pumuki_package_version`, `pre_commit_policy_hash`, `pre_commit_policy_bundle`. Con `pumuki doctor --parity` (y opcionalmente `--json`), Pumuki calcula el perfil actual y, si existe el fichero esperado, rellena `parity_comparison`; cualquier desajuste hace **exit code 1**.
+
+## Evidencia en PRE_COMMIT con índice solo documentación
+
+- `PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE` (`1|true|yes`): fuerza el `git add` automático de `.ai_evidence.json` después de un `PRE_COMMIT` exitoso aunque el índice solo contenga rutas `*.md` / `*.mdx` (además de la propia evidencia). Por defecto, en ese alcance Pumuki **no** ensarta la evidencia en el commit: el snapshot se refresca en disco y puedes decidir si lo incluyes (`git add -- .ai_evidence.json`). Cubre el caso de commits puramente documentales sin mezclar un diff grande de evidencia (p. ej. informes upstream tipo PUMUKI-INC-069).
+
 ## Evidencia en PRE_PUSH con `.ai_evidence.json` trackeado
 
 - `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE` (`1|true|yes`): fuerza la escritura del snapshot en `PRE_PUSH` aunque `.ai_evidence.json` esté versionado. Por defecto (sin esta variable), si el fichero está en el índice de git y el outcome no es `BLOCK`, Pumuki **no** muta el archivo para no romper hooks encadenados (p. ej. `pre-commit` ejecutado desde `pre-push`).

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
@@ -123,7 +130,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`
 
@@ -242,7 +252,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`. 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`. **`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 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`).
@@ -287,6 +297,8 @@ npx --yes pumuki install --with-mcp --agent=codex
 npx --yes pumuki doctor
 # include deterministic adapter/mcp wiring health checks
 npx --yes pumuki doctor --deep --json
+# parity profile vs .pumuki/ci-parity-expected.json (CI/local alignment)
+npx --yes pumuki doctor --parity --json
 
 # show lifecycle status
 npx --yes pumuki status
@@ -563,6 +575,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.
@@ -671,7 +684,9 @@ npm run toolkit:clean-artifacts -- --dry-run
 
 - Reads staged changes with `git diff --cached --name-status`.
 - Builds facts from staged content.
+- Opcional: `PUMUKI_GATE_SCOPE_PATH_PREFIXES` acota el primer alcance de hechos a prefijos del monorepo (ver `docs/product/CONFIGURATION.md`).
 - Requires valid SDD/OpenSpec status (session + active change + validation).
+- Si `.ai_evidence.json` está **versionado** y el hook refresca el snapshot en disco tras un gate **no** bloqueante, por defecto Pumuki vuelve a hacer `git add` de ese fichero **salvo** que lo único en el índice (ignorando `.ai_evidence.json` / `.AI_EVIDENCE.json`) sean rutas de documentación (`*.md`, `*.mdx`). En ese caso la evidencia se actualiza en disco pero **no** se ensarta en el commit: puedes añadirla manualmente (`git add -- .ai_evidence.json`) o activar el comportamiento anterior con `PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE=1` (ver `docs/product/CONFIGURATION.md`). En stderr (si no va en modo silencioso) verás un aviso `[pumuki][evidence-sync]`.
 
 ### PRE_PUSH
 
@@ -711,11 +726,15 @@ Cada ejecución del gate escribe evidencia determinista en:
 
 - `.ai_evidence.json`
 
-Excepción: en `PRE_PUSH`, si el fichero está trackeado y el outcome no es `BLOCK`, la escritura al path anterior se omite (ver sección PRE_PUSH arriba). La telemetría interna del gate sigue generándose; solo se evita mutar el árbol de trabajo.
+Excepciones:
+
+- En `PRE_PUSH`, si el fichero está trackeado y el outcome no es `BLOCK`, la escritura al path anterior se omite (ver sección PRE_PUSH arriba). La telemetría interna del gate sigue generándose; solo se evita mutar el árbol de trabajo.
+- En `PRE_COMMIT`, si el fichero está trackeado y el índice es solo documentación (`*.md` / `*.mdx`), el fichero puede actualizarse en disco sin auto-`git add` (ver sección PRE_COMMIT arriba).
 
 Schema and behavior:
 
 - `version: "2.1"` is the source of truth
+- `operational_hints` (opcional pero recomendado en runs recientes): `requires_second_pass` (boolean), `second_pass_reason` (string o null), `human_summary_lines` (1–4 líneas legibles), `rule_execution_breakdown` (conteos evaluated / blocking / warn / info / skipped out-of-scope). Útil para tooling y para entender el resultado sin abrir todo el snapshot.
 - `snapshot` + `ledger`
 - `platforms` and `rulesets` tracking
 - `snapshot.sdd_metrics` tracks stage-level SDD enforcement metadata
@@ -798,6 +817,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,111 @@
+# 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.
+
+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/integrations/evidence/buildEvidence.ts

@@ -7,6 +7,7 @@ import type {
   ConsolidationSuppressedFinding,
   CompatibilityViolation,
   EvidenceLines,
+  EvidenceOperationalHints,
   HumanIntentState,
   LedgerEntry,
   PlatformState,
@@ -23,6 +24,7 @@ import { buildSnapshotPlatformSummaries } from './platformSummary';
 import { resolveHumanIntent } from './humanIntent';
 import { normalizeSnapshotEvaluationMetrics } from './evaluationMetrics';
 import { normalizeSnapshotRulesCoverage } from './rulesCoverage';
+import { buildEvidenceOperationalHints } from './operationalHints';
 
 type BuildFindingInput = Finding & {
   file?: string;
@@ -50,6 +52,9 @@ export type BuildEvidenceParams = {
   };
   sddMetrics?: SddMetrics;
   repoState?: RepoState;
+  operationalHintsExtra?: Partial<
+    Pick<EvidenceOperationalHints, 'requires_second_pass' | 'second_pass_reason'>
+  >;
 };
 
 const normalizeLines = (lines?: EvidenceLines): EvidenceLines | undefined => {
@@ -766,9 +771,19 @@ export function buildEvidence(params: BuildEvidenceParams): AiEvidenceV2_1 {
     previousEvidence: params.previousEvidence,
   });
 
+  const operational_hints = buildEvidenceOperationalHints({
+    stage: params.stage,
+    outcome,
+    findings: normalizedFindings,
+    rulesCoverage: normalizedRulesCoverage,
+    evaluationMetrics: normalizedEvaluationMetrics,
+    extra: params.operationalHintsExtra,
+  });
+
   return {
     version: '2.1',
     timestamp: now,
+    operational_hints,
     snapshot: {
       stage: params.stage,
       audit_mode: params.auditMode ?? 'gate',

package/integrations/evidence/operationalHints.ts

@@ -0,0 +1,110 @@
+import type { GateOutcome } from '../../core/gate/GateOutcome';
+import type { GateStage } from '../../core/gate/GateStage';
+import { resolveRemediationHintOrDefault } from '../gate/remediationCatalog';
+import type {
+  EvidenceOperationalHints,
+  EvidenceRuleExecutionBreakdown,
+  SnapshotEvaluationMetrics,
+  SnapshotFinding,
+  SnapshotRulesCoverage,
+} from './schema';
+
+const truncate = (value: string, max: number): string => {
+  const t = value.trim();
+  if (t.length <= max) {
+    return t;
+  }
+  return `${t.slice(0, max - 1)}…`;
+};
+
+const buildRuleExecutionBreakdown = (params: {
+  findings: ReadonlyArray<SnapshotFinding>;
+  rulesCoverage?: SnapshotRulesCoverage;
+  evaluationMetrics?: SnapshotEvaluationMetrics;
+}): EvidenceRuleExecutionBreakdown => {
+  const matched_blocking_count = params.findings.filter(
+    (f) =>
+      f.severity === 'ERROR' ||
+      f.severity === 'CRITICAL' ||
+      f.blocking === true
+  ).length;
+  const matched_warn_count = params.findings.filter((f) => f.severity === 'WARN').length;
+  const matched_info_count = params.findings.filter((f) => f.severity === 'INFO').length;
+  const evaluated_count =
+    params.rulesCoverage?.counts?.evaluated ?? params.evaluationMetrics?.evaluated_rule_ids.length ?? 0;
+  const active = params.rulesCoverage?.counts?.active ?? 0;
+  const evaluatedFromCoverage = params.rulesCoverage?.counts?.evaluated;
+  const skipped_out_of_scope_count =
+    typeof params.rulesCoverage?.counts?.unevaluated === 'number'
+      ? params.rulesCoverage.counts.unevaluated
+      : active > 0 && typeof evaluatedFromCoverage === 'number'
+        ? Math.max(0, active - evaluatedFromCoverage)
+        : 0;
+
+  return {
+    evaluated_count: Math.max(0, evaluated_count),
+    matched_blocking_count,
+    matched_warn_count,
+    matched_info_count,
+    skipped_out_of_scope_count: Math.max(0, skipped_out_of_scope_count),
+  };
+};
+
+const buildHumanSummaryLines = (params: {
+  stage: GateStage;
+  outcome: GateOutcome;
+  findings: ReadonlyArray<SnapshotFinding>;
+}): string[] => {
+  const lines: string[] = [`${params.stage}: outcome=${params.outcome}.`];
+  if (params.outcome === 'BLOCK') {
+    const blocking =
+      params.findings.find((f) => f.severity === 'CRITICAL' || f.severity === 'ERROR') ??
+      params.findings.find((f) => f.blocking === true) ??
+      params.findings[0];
+    if (blocking) {
+      lines.push(`${blocking.code}: ${truncate(blocking.message, 140)}`);
+      lines.push(resolveRemediationHintOrDefault(blocking.code));
+    }
+    return lines.slice(0, 3);
+  }
+  const warn = params.findings.find((f) => f.severity === 'WARN');
+  if (warn) {
+    lines.push(`WARN ${warn.code}: ${truncate(warn.message, 120)}`);
+  }
+  return lines.slice(0, 3);
+};
+
+export const buildEvidenceOperationalHints = (params: {
+  stage: GateStage;
+  outcome: GateOutcome;
+  findings: ReadonlyArray<SnapshotFinding>;
+  rulesCoverage?: SnapshotRulesCoverage;
+  evaluationMetrics?: SnapshotEvaluationMetrics;
+  extra?: Partial<Pick<EvidenceOperationalHints, 'requires_second_pass' | 'second_pass_reason'>>;
+}): EvidenceOperationalHints => {
+  const breakdown = buildRuleExecutionBreakdown({
+    findings: params.findings,
+    rulesCoverage: params.rulesCoverage,
+    evaluationMetrics: params.evaluationMetrics,
+  });
+  let human_summary_lines = buildHumanSummaryLines({
+    stage: params.stage,
+    outcome: params.outcome,
+    findings: params.findings,
+  });
+  if (params.extra?.requires_second_pass === true) {
+    human_summary_lines = [
+      ...human_summary_lines,
+      'La evidencia trackeada se actualizó en disco pero no entró en el índice; si debe ir en este commit: git add -- .ai_evidence.json',
+    ];
+  }
+  return {
+    requires_second_pass: params.extra?.requires_second_pass ?? false,
+    second_pass_reason:
+      params.extra?.requires_second_pass === true
+        ? (params.extra.second_pass_reason ?? null)
+        : null,
+    human_summary_lines: human_summary_lines.slice(0, 4),
+    rule_execution_breakdown: breakdown,
+  };
+};

package/integrations/evidence/schema.ts

@@ -206,10 +206,26 @@ export type EvidenceChain = {
   sequence: number;
 };
 
+export type EvidenceRuleExecutionBreakdown = {
+  evaluated_count: number;
+  matched_blocking_count: number;
+  matched_warn_count: number;
+  matched_info_count: number;
+  skipped_out_of_scope_count: number;
+};
+
+export type EvidenceOperationalHints = {
+  requires_second_pass: boolean;
+  second_pass_reason: string | null;
+  human_summary_lines: string[];
+  rule_execution_breakdown?: EvidenceRuleExecutionBreakdown;
+};
+
 export type AiEvidenceV2_1 = {
   version: '2.1';
   timestamp: string;
   evidence_chain?: EvidenceChain;
+  operational_hints?: EvidenceOperationalHints;
   snapshot: Snapshot;
   ledger: LedgerEntry[];
   platforms: Record<string, PlatformState>;

package/integrations/evidence/writeEvidence.ts

@@ -342,6 +342,9 @@ const toStableEvidence = (
   return {
     version: '2.1',
     timestamp: evidence.timestamp,
+    ...(typeof evidence.operational_hints !== 'undefined'
+      ? { operational_hints: evidence.operational_hints }
+      : {}),
     snapshot: {
       stage: evidence.snapshot.stage,
       audit_mode: normalizedAuditMode,

package/integrations/gate/remediationCatalog.ts

@@ -0,0 +1,40 @@
+export const DEFAULT_GATE_REMEDIATION =
+  'Corrige la causa del bloqueo y vuelve a ejecutar el gate.';
+
+export const REMEDIATION_HINT_BY_CODE: Readonly<Record<string, string>> = {
+  EVIDENCE_MISSING: 'Regenera .ai_evidence.json ejecutando una auditoría.',
+  EVIDENCE_INVALID: 'Corrige/regenera .ai_evidence.json y vuelve a ejecutar el gate.',
+  EVIDENCE_CHAIN_INVALID: 'Regenera evidencia para restaurar la cadena criptográfica.',
+  EVIDENCE_STAGE_SYNC_FAILED:
+    'Sincroniza la evidencia trackeada y reintenta: git add -- .ai_evidence.json && git commit --amend --no-edit',
+  EVIDENCE_STALE: 'Refresca evidencia antes de continuar.',
+  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este mismo repositorio.',
+  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual y reintenta.',
+  EVIDENCE_RULES_COVERAGE_MISSING: 'Ejecuta auditoría completa para recalcular rules_coverage.',
+  EVIDENCE_RULES_COVERAGE_INCOMPLETE: 'Asegura coverage_ratio=1 y unevaluated=0.',
+  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',
+  EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
+    'Reconcilia policy/skills y revalida PRE_WRITE: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
+  GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
+  EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
+    'Reduce archivos staged/unstaged por debajo del umbral (o ajusta PUMUKI_PREWRITE_WORKTREE_*); divide el trabajo en commits más pequeños.',
+  EVIDENCE_PREWRITE_WORKTREE_WARN:
+    'El worktree supera el umbral de aviso; reduce alcance antes del siguiente commit/push.',
+  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta: git push --set-upstream origin <branch>',
+  PRE_PUSH_UPSTREAM_MISALIGNED:
+    'Alinea upstream con la rama actual: git branch --unset-upstream && git push --set-upstream origin <branch>',
+  MANIFEST_MUTATION_DETECTED:
+    'Los hooks/gates no deben modificar manifests. Revisa wiring y ejecuta upgrade explícito solo cuando aplique (por ejemplo: pumuki update --latest).',
+};
+
+export const resolveRemediationHintForViolationCode = (code: string): string | undefined => {
+  const trimmed = code.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  return REMEDIATION_HINT_BY_CODE[trimmed];
+};
+
+export const resolveRemediationHintOrDefault = (code: string): string =>
+  resolveRemediationHintForViolationCode(code) ?? DEFAULT_GATE_REMEDIATION;

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')