Stack My Architecture — Curso Pumuki

Quinto curso del ecosistema Stack My Architecture: Pumuki como capa de enforcement determinista (Facts → Rules → Gate → evidencia v2.1) en repos reales.

Qué ofrece este curso (y qué no)

• Sí: narrativa en prosa, semana a semana, del contrato de Pumuki, los stages, la instalación razonada, los perfiles de adopción, el encaje con SDD y Governance, monorepo/parity, un mapa completo del producto (CLI, hooks, MCP, todas las tools enterprise documentadas) y un cierre con checklist operativa.
• No: sustituye el README ni el USAGE del paquete npm: siguen siendo la fuente normativa. Si algo contradice el repo ast-intelligence-hooks, manda el producto y este curso se corrige.

Empieza por 02-modulos/00-mapa-completo-del-producto.md si quieres el mapa antes de la historia lineal.

Público objetivo

Equipos que ya gobiernan el cambio con Governance y/o ejecutan flujo SDD + IA, y quieren operar hooks, CLI, CI, MCP y remediaciones sin confundir enforcement con arquitectura de producto.

Prerrequisitos recomendados

• Curso Governance (AGENTS.md, skills, gates, release) o experiencia equivalente.
• Curso IA + SDD (OpenSpec, validación, cierre de tickets) o experiencia equivalente.

Este curso no reenseña OpenSpec ni ADR: enlaza a esos cursos y profundiza en cómo Pumuki enforcementa lo que allí acordasteis.

Versión mínima del paquete npm

• pumuki >= 6.3.71 (MVP del curso; repinear cuando el producto publique una release estable posterior).

Lab de práctica

Por defecto se trabaja sobre una variante o fork del proyecto del curso Governance (GovernanceKit) o del curso SDD (HelpdeskSDD), para no inventar dominio nuevo. Elige uno en 00-preparacion/02-lab-governancekit-helpdesksdd.md y mantenlo durante todas las unidades con actividad en lab (incluidas 08–12).

Cómo generar el HTML local

python3 scripts/build-html.py

Salida: dist/curso-stack-my-architecture-pumuki.html y dist/index.html.

Validación del repo del curso

python3 scripts/validate-course-structure.py
python3 scripts/check-links.py

courseId (hub / progreso)

• stack-my-architecture-pumuki

Seguimiento de la iniciativa (repo producto Pumuki)

En el repositorio ast-intelligence-hooks: docs/tracking/plan-curso-pumuki-stack-my-architecture.md.

Bienvenida — Curso Pumuki

Por qué existe este curso

Si llegas aquí desde Stack My Architecture, ya sabes que el ecosistema separa con intención arquitectura de producto, gobernanza del cambio y flujo SDD con IA. Pumuki ocupa un lugar muy concreto: es la capa de enforcement determinista que se ejecuta donde el código vive (hooks, CI, opcionalmente MCP frente a un agente). No decide qué feature construyes; cierra el círculo entre lo que tu equipo dijo que era obligatorio (skills, políticas, OpenSpec) y lo que realmente se está commiteando o empujando.

Este curso no es un índice de enlaces. Es un recorrido en prosa: semana a semana construyes una mentalidad operativa — la misma que necesitas cuando, a las tres de la mañana, un hook bloquea un push y alguien pregunta “¿es el gate o es Pumuki o es SDD o es Git?”.

Qué vas a ser capaz de hacer al cerrar el MVP

1. Explicar en una frase qué hace Pumuki y qué deja fuera de su responsabilidad, sin mezclarlo con el producto de negocio ni con los tests de dominio.
2. Seguir el pipeline Facts → Rules → Gate → evidencia v2.1 y relacionarlo con lo que ves en .ai_evidence.json, en stderr del hook y en doctor --json.
3. Instalar y validar un consumidor: install, doctor, status, y un sdd validate acorde a tu stage.
4. Elegir un perfil de adopción (mínimo, estándar SDD, enterprise) sabiendo qué regalas cuando bajas de nivel.
5. Enlazar Pumuki con el curso de SDD (OpenSpec, sesión, códigos de error) y con el de Governance (AGENTS.md, skills, GitFlow) sin duplicar esos contenidos.
6. Razonar sobre MCP: qué servidor usar para leer evidencia, cuál para contexto enterprise, qué tools existen y por qué algunas son experimentales.
7. Operar el menú (pumuki-framework), la matrix no interactiva y el pre-flight sin confundirlos con el resultado canónico de CI.
8. Configurar o explicar notificaciones (macOS / stderr) y watch local sin spam.
9. Aterrizar monorepo (prefijos de scope) y parity local vs CI cuando tu organización lo exija.
10. Cerrar con una checklist de release que podrías defender ante un tech lead.

Cómo está narrado el curso

• 02-modulos/00-mapa-completo-del-producto.md es la brújula: mapa de stages, CLI, MCP, tools y evidencia. Léelo antes o en paralelo con el módulo 1; ahí no se cuenta una historia lineal, se fija el territorio.
• Tras el mapa, la secuencia pedagógica va contrato → instalación → ciclo de vida → evidencia → perfiles → SDD ampliado → menú → MCP → notificaciones/watch → Governance → monorepo → cierre (ver 01-roadmap/00-modulos-nucleo.md).
• Cada unidad incluye objetivo observable, no confundas, actividad y criterio de dominio: no es decoración; es cómo comprobamos que aprendiste.
• Cada módulo termina con práctica en tu lab (GovernanceKit o HelpdeskSDD, según 00-preparacion/02-lab-governancekit-helpdesksdd.md). Sin lab, el curso se queda en teoría; con lab, el gate te habla.

Documentación canónica del producto (la fuente de verdad)

Todo lo que afirmamos aquí debe poder rematar en estos documentos del repo ast-intelligence-hooks (o en el paquete publicado en npm):

Regla pedagógica: si este curso y el README chocan, gana el README y el USAGE del producto; este texto se actualiza.

Orden de lectura

1. 01-roadmap/00-roadmap-mvp.md y 01-roadmap/00-modulos-nucleo.md (vista rápida y secuencia real).
2. 02-modulos/00-mapa-completo-del-producto.md (territorio; referencia durante todo el curso).
3. Módulos en el orden del roadmap (incluye 08–12 entre núcleo y Governance).
4. docs/playbook-pumuki-sdd-bridge.md cuando diseñes rituales de equipo SDD + Pumuki.

Bienvenida al enforcement con los ojos abiertos: Pumuki te va a decir que no a veces. Ese “no” es el diseño funcionando, no un insulto a tu talento.

Versión mínima y referencias

Versión mínima (MVP del curso)

• Paquete npm pumuki >= 6.3.71.

Comprueba en el repo consumidor:

npx pumuki --version
npx pumuki status
npx pumuki doctor --json

Si el curso y el hub publican una release posterior del producto, actualiza la versión mínima en este archivo, en README.md y en el CHANGELOG del curso.

Referencias de producto (lectura obligatoria dispersa)

Cursos Stack My Architecture relacionados

• Governance: política, AGENTS.md, skills, gates de calidad, release.
• IA + SDD: OpenSpec, validación, cierre de tickets (este curso enlaza al playbook Kanban del SDD donde aplique).

Lab: GovernanceKit vs HelpdeskSDD

El curso asume un proyecto de práctica ya definido en los otros cursos para no inventar dominio.

Opción A — GovernanceKit (recomendada si priorizas policy y gates)

Continúa el hilo del curso Governance: mismo repo o fork donde ya tengas AGENTS.md, skills y rutinas de gate. Pumuki debe convivir con esa política sin duplicar el rol de “fuente de verdad” humana.

Opción B — HelpdeskSDD (recomendada si priorizas OpenSpec y validate)

Continúa el hilo del curso SDD: mismo repo o fork donde ejecutes validate y cierres de ticket. Pumuki debe acoplarse al flujo SDD experimental cuando active PUMUKI_EXPERIMENTAL_SDD.

Decisión

Documenta en una línea tu elección y el path del repo:

• Lab elegido: GovernanceKit / HelpdeskSDD
• Ruta local del clone: ________________________

Mantén la misma elección hasta el módulo 7.

Roadmap MVP (orden de trabajo)

Secuencia para recorrer el curso en el hub. Cada bloque enlaza a material en 02-modulos/.

Antes de la semana 1 (lectura de territorio)

• 02-modulos/00-mapa-completo-del-producto.md — mapa único: stages, CLI, MCP, tools, evidencia. Sin esto, los módulos suenan a lista de enlaces.

Semanas 1–7

1. Semana 1 — Contrato y límites → 02-modulos/01-contrato-y-limites.md
2. Semana 2 — Primer verde → 02-modulos/02-instalacion-y-primer-verde.md
3. Semana 3 — Perfiles de adopción → 02-modulos/03-perfiles-de-adopcion.md
4. Semana 4 — SDD + Pumuki → 02-modulos/04-sdd-y-pumuki.md y docs/playbook-pumuki-sdd-bridge.md
5. Semana 5 — Governance + Pumuki → 02-modulos/05-governance-y-pumuki.md
6. Semana 6 — Monorepo / CI / parity → 02-modulos/06-monorepo-ci-parity.md
7. Semana 7 — Proyecto final → 02-modulos/07-proyecto-final-checklist.md

Paralelamente: integración en stack-my-architecture-hub (/pumuki/) y enlaces desde cursos Governance y SDD.

Entregable final

• Repo lab con Pumuki operativo en el perfil elegido.
• Evidencia de doctor --json y checklist del módulo 7 completada con narrativa (no solo casillas).

Relación con el README del producto

Este curso ordena y narra; la fuente normativa sigue siendo README.md y docs/product/USAGE.md de ast-intelligence-hooks. Si hay divergencia, se actualiza el curso.

Módulos núcleo — mapa rápido

Orden de primera lectura alineado al diseño pedagógico (plan-curso-pumuki-stack-my-architecture.md en el repo producto): primero contrato e instalación, luego ciclo de vida y evidencia, después perfil y SDD ampliado, operación humana (menú, MCP, notificaciones/watch), y cierre Governance / monorepo / checklist.

Profundiza en el curso Governance y en IA + SDD del hub donde este curso solo enlaza.

Playbook — Puente SDD ↔ Pumuki

Objetivo: cuando el flujo OpenSpec del curso IA + SDD entra en fase de verificación o cierre, Pumuki debe dar señales accionables sin sustituir el Kanban ni las specs.

Activación

• Variable PUMUKI_EXPERIMENTAL_SDD: comportamiento experimental alineado al flujo SDD (ver docs/product/USAGE.md en ast-intelligence-hooks).

Comandos de comprobación

• npx pumuki sdd status / rutas documentadas en USAGE.md para validación SDD.
• Interpretar códigos OPENSPEC_ y SDD_: cada código debe mapearse a una acción concreta (corregir spec, ampliar tests, desbloquear gate, etc.).

Enlace pedagógico

En el curso SDD, usa el playbook Kanban y las semanas de verificación como marco temporal; en este curso solo registras qué parte del output de Pumuki alimenta el cierre del ticket.

No hacer aquí

• No redactar OpenSpec completo ni ADR: vuelve al curso SDD o Governance.

Mapa completo del producto Pumuki

Este documento es la brújula del curso. Léelo cuando quieras ver el bosque entero antes de entrar en cada árbol. Todo lo que sigue está alineado con el repositorio ast-intelligence-hooks (paquete npm pumuki) y con docs/product/USAGE.md, docs/mcp/mcp-servers-overview.md y el README.md del producto.

1. Una sola idea que lo atraviesa todo

Pumuki implementa un mismo modelo de ejecución en el portátil, en los hooks de Git, en CI y (opcionalmente) frente a un agente de IA: primero se extraen hechos del código o del diff que toca en cada momento; después se evalúan reglas que tu organización ha decidido que importan; a continuación un gate por stage decide si puedes continuar, solo con advertencias, o si debe bloquearse el flujo; y al final queda evidencia versionada en .ai_evidence.json (contrato v2.1) para auditoría y para que otras herramientas (IDE, MCP, scripts) lean el mismo veredicto que vio el hook.

No hay dos “verdades” distintas: el menú interactivo, pumuki-pre-commit, el servidor MCP y pumuki doctor hablan del mismo pipeline cuando están bien configurados. Si algo “cuadra en el IDE pero no en el push”, casi siempre es versión distinta, scope distinto (staged vs rango de commits) o evidencia caducada o inválida, no magia negra.

2. Los cuatro stages que debes saber de memoria

Cada stage tiene umbrales de severidad (blockOnOrAbove, warnOnOrAbove) definidos en políticas del producto. No necesitas memorizar los números: necesitas entender que ERROR suele bloquear y WARN puede avisar según el stage.

3. Superficies donde “vive” Pumuki (sin solaparlos)

3.1 Paquete npm y binarios

Instalas pumuki como dependencia. Desde ahí salen, entre otros:

• pumuki — CLI principal: install, doctor, status, bootstrap, sdd …, etc.
• pumuki-pre-write, pumuki-pre-commit, pumuki-pre-push, pumuki-ci — runners que Git o CI invocan; son la cara del gate en cada momento.
• pumuki-framework — menú interactivo para consumidores (npx pumuki-framework).
• pumuki-mcp-evidence, pumuki-mcp-enterprise — servidores MCP en HTTP.
• pumuki-mcp-evidence-stdio, pumuki-mcp-enterprise-stdio — puentes stdio para que Cursor, Codex, Claude, etc. hablen el protocolo MCP sin que tú abras puertos a mano.

Hecho pedagógico clave: los hooks no dependen de MCP. MCP es capa opcional para agentes y para lectura rica de contexto. Si alguien te dice “no usamos MCP, entonces no tenemos Pumuki”, está confundiendo enforcement (hooks/CI) con superficie de agente.

3.2 Postinstall y lifecycle

En repos Git, versiones recientes pueden ejecutar pumuki install en postinstall para dejar hooks y lifecycle alineados. Eso explica por qué “solo con npm install” a veces cambia .git/hooks: es intencional, no un virus. En CI suele saltarse (CI=true). Puedes desactivarlo con PUMUKI_SKIP_POSTINSTALL=1 si tu equipo tiene un motivo documentado.

3.3 Menú interactivo (pumuki-framework)

Es una consola de diagnóstico y flujo para humanos. En modo Consumer prioriza opciones de lectura alineadas con PRE_COMMIT/PRE_PUSH; en Advanced aparece más superficie (legacy, toolkits). Pedagógicamente: el menú no es la fuente de verdad del diseño; el diseño es el gate por stage. El menú es un tablero de mandos para quien no quiere memorizar flags.

3.4 OpenSpec / SDD

En perfil enterprise, Pumuki corta el camino si OpenSpec o la sesión SDD no están en un estado válido. Los códigos (OPENSPEC_MISSING, SDD_SESSION_INVALID, etc.) no son decoración: son contratos que verás en JSON y en stderr. El curso del IA + SDD te enseña el método; este curso te enseña cómo Pumuki lo enforcementa.

4. MCP: qué servidores existen y qué problema resuelve cada uno

4.1 Evidence Context Server (pumuki-mcp-evidence)

• Propósito: exponer solo lectura el estado de .ai_evidence.json v2.1 por HTTP.
• Puerto por defecto: 7341, host 127.0.0.1, ruta base /ai-evidence (configurable con PUMUKI_EVIDENCE_*).
• Mentalidad: “¿Qué dice la última evidencia sin ejecutar el gate otra vez?” — útil para dashboards y para agentes que deben leer antes de proponer código.

Si el fichero falta o no es v2.1 válido, los endpoints de payload pueden responder 404: eso no es un bug del servidor, es el contrato (no inventar evidencia).

4.2 Enterprise MCP Server (pumuki-mcp-enterprise)

• Propósito: consolidar recursos (estado de evidencia, gitflow, SDD, lifecycle…) y herramientas (tools) en un solo servidor HTTP.
• Puerto por defecto: 7391 (PUMUKI_ENTERPRISE_MCP_*). PUMUKI_ENTERPRISE_MCP_PORT=0 pide puerto efímero si chocas con EADDRINUSE.

4.3 Puentes stdio

Los binarios *-stdio levantan el mismo contrato para clientes MCP que no consumen HTTP directamente. Son la forma habitual en IDEs.

5. Catálogo de tools del MCP enterprise (una a una)

Aparecen en el catálogo HTTP GET /tools (y vía stdio). Metadatos típicos: name, description, mutating, safeByDefault.

Herramientas “experimentales” del enterprise (ai_gate_check, pre_flight_check, auto_execute_ai_start) solo se listan si activas el feature experimental de MCP enterprise (p. ej. PUMUKI_EXPERIMENTAL_MCP_ENTERPRISE=advisory o strict). Si no, el servidor sigue vivo pero no te “vende” herramientas que tu organización considera opt-in.

Regla de oro: ninguna tool mutante te va a reescribir historia de Git alegremente desde MCP en el baseline seguro: primero política y sesión, después acción.

6. CLI que no puedes ignorar (qué pregunta responde cada una)

Si solo recuerdas tres comandos para empezar: install, doctor --json, sdd validate --stage=PRE_COMMIT.

7. Evidencia v2.1 y skills (visión de pájaro)

• .ai_evidence.json: el “parte médico” del último gate relevante: findings, cobertura de reglas, métricas de severidad, metadatos. Debe ser coherente con la cadena de validación (evidence_chain cuando aplica).
• Skills / reglas: se resuelven en orden core → repo (skills.lock.json) → custom (.pumuki/custom-rules.json) con conflicto custom > repo > core por ruleId. Las reglas AUTO exigen detector mapeado; si no, el gate puede bloquear por cobertura incompleta.

8. Cómo usar este mapa en el curso

• Módulo 1 profundiza en contrato y límites (qué promete Pumuki y qué no).
• Módulo 2 te lleva al primer verde con comandos reales.
• Módulo 3 elige perfil de adopción sin autoengañarse.
• Módulos 4 y 5 enlanzan SDD y Governance sin duplicar esos cursos.
• Módulo 6 aterriza monorepo y parity.
• Módulo 7 cierra con checklist profesional.

Si en algún momento sientes que “esto es demasiado superficie”, vuelve aquí y baja al documento enlazado del producto: este curso no sustituye el manual; te ordena el manual en una narrativa.

Referencias canónicas (profundizar siempre)

• README.md del producto
• docs/product/USAGE.md
• docs/product/INSTALLATION.md
• docs/product/CONFIGURATION.md
• docs/mcp/mcp-servers-overview.md
• docs/mcp/ai-evidence-v2.1-contract.md
• AGENTS.md (en repos que adopten el contrato de agentes)

Módulo 1 — Contrato y límites

1.1 Qué es Pumuki (sin marketing)

Imagina un inspector de obra que no opina del color del salón, pero sí comprueba que cables, tierra y normativa están donde la ley y el proyecto dijeron. Pumuki es ese inspector para el cambio de software: mira hechos detectables en el código o en el diff, los cruza con reglas que vienen de skills y políticas, y emite un veredicto por etapa del flujo Git (PRE_WRITE, PRE_COMMIT, PRE_PUSH, CI). Ese veredicto queda escrito en .ai_evidence.json (versión 2.1) para que humanos, CI y agentes lean la misma película.

Eso es todo el núcleo. Lo demás (menú bonito, MCP, notificaciones en macOS) son accesorios para que el núcleo sea usable en la vida real.

1.2 El pipeline en una frase continua

Facts: “¿Qué hay en este diff?” — tipos de archivo, plataformas inferidas (iOS, Android, backend, frontend), heurísticas, AST cuando aplica.

Rules: “¿Qué dijimos que había que cumplir?” — core embebido, skills.lock.json del repo, reglas custom en .pumuki/custom-rules.json, con precedencia custom > repo > core por identificador de regla.

Gate: “¿Con esta severidad y este stage, pasamos o paramos?” — no es un voto humano; es política + umbrales.

Evidencia: “¿Qué quedó registrado para auditoría y para la siguiente herramienta?” — contrato v2.1, con telemetría de cobertura de reglas y proyecciones de severidad.

Si enseñas Pumuki sin ese orden, el alumno mezcla síntoma (“me bloqueó el push”) con causa (“PRE_PUSH vio WARN tratado como bloqueo en mi policy” o “evidencia inválida”).

1.3 Qué no es Pumuki (límites que debes defender ante el equipo)

1. No es la aplicación que vendes al usuario final. Si Pumuki “falla”, tu negocio puede seguir en producción; lo que falla es el contrato de entrega en ese repo.
2. No sustituye tests de dominio, contratos de API, E2E ni criterios de aceptación del product owner. Puede convivir con ellos; no los implica.
3. No reemplaza el criterio humano en revisión de código: automatiza políticas acordadas. Si la política es mala, el gate será consistentemente malo.
4. No es “el mismo SDD”: OpenSpec/SDD es un método de cambio; Pumuki puede exigir que el método esté en orden antes de ejecutar el gate enterprise. Confundir ambos genera la frase tóxica “Pumuki no me deja programar” cuando en realidad SDD_SESSION_INVALID te está diciendo “no hay cambio activo coherente”.
5. No es opcional en la cabeza del alumno si el repo ya lo adoptó: o lo entendéis como contrato, o lo desinstaláis. El peor estado es “instalado pero ignorado”.

1.4 Stages y la pregunta que hace cada uno

Cuando leas docs/product/USAGE.md, fíjate en la tabla de stages: cada uno tiene un scope distinto. Pedagógicamente:

• PRE_COMMIT pregunta: “¿Lo que ya metiste en el índice cumple?”
• PRE_PUSH pregunta: “¿Lo que vas a subir respecto a upstream cumple y el contexto Git tiene sentido (rama, tracking, etc.)?”
• CI pregunta: “¿En el rango que ve el integrador, seguimos cumpliendo?”

Si el alumno ejecuta solo PRE_COMMIT en local y asume que el push es seguro, no ha entendido PRE_PUSH.

1.5 Cobertura de reglas (por qué a veces bloquea “sin findings bonitos”)

En stages clave, Pumuki puede bloquear si hay reglas activas que no se evaluaron, o reglas AUTO sin detector mapeado. Eso es intencional: evita que un equipo se crea “100 % governance” con reglas fantasmas. Enseña esto antes del primer bloqueo incomprensible.

Ejercicio (lab obligatorio)

En tu repo lab, abre un archivo que dispare una regla clara (por ejemplo una heurística de TypeScript o iOS que ya conozcas del producto). Sin ejecutar aún el hook, escribe en tres líneas:

1. Qué fact concreto detectará Pumuki (path, patrón, plataforma).
2. Qué ruleId o familia de regla lo cubre (aunque sea buscando en la salida de un gate de prueba).
3. Si esperas WARN o BLOCK en PRE_COMMIT con tu policy actual.

Luego ejecuta un solo stage (pumuki-pre-commit o el que tengas cableado) y compara tu predicción con .ai_evidence.json. Si no cuadra, no sigas al módulo 2 hasta saber por qué.

Lectura mínima del producto

• README.md — secciones “Qué NO es Pumuki” y “Enterprise Execution Model”.
• docs/product/USAGE.md — “Gate stages and policies” y “Skills rules engine”.
• 02-modulos/00-mapa-completo-del-producto.md — repaso del territorio.

Módulo 2 — Instalación y primer verde

2.1 Qué significa “verde” aquí

Verde no es “mi app compila”. Es: hooks y lifecycle alineados, versión efectiva coherente entre lo instalado y lo que el repo espera, doctor sin bloqueos que tu política considere críticos, y un stage (normalmente PRE_COMMIT) que ejecutas a propósito y entiendes su salida. Si saltas directo a “ya hice npm install”, te has saltado la mitad del aprendizaje.

2.2 Instalación mínima razonada

En un repo Git con Node 18+ y npm 9+:

npm install --save-exact pumuki

Por qué --save-exact: Pumuki evoluciona rápido; una tilde que sube de parche en CI puede cambiar el comportamiento de hooks. En formación enterprise es norma fijar versión.

A partir de versiones recientes, el postinstall puede ejecutar pumuki install solo en contexto Git (no en CI típico). Eso crea o actualiza hooks y artefactos de lifecycle. Si tu equipo no quiere eso en npm install, la válvula documentada es PUMUKI_SKIP_POSTINSTALL=1 — pero entonces tú asumes instalar hooks explícitamente.

Bootstrap enterprise (cuando el README del producto lo recomienda para greenfield):

npx --yes pumuki bootstrap --enterprise --agent=codex

Sustituye codex por el agente que uses (cursor, claude, etc.) si quieres adapters y MCP listos. El bootstrap no es magia: solo orquesta pasos que podrías hacer a mano; lo enseñamos porque en equipos reales nadie los hace bien a mano la primera vez.

2.3 Los tres comandos que debes enseñar el primer día

npx pumuki doctor --json
npx pumuki status --json
npx pumuki install

doctor --json: es el informe médico máquina-legible. Campos como version.effective, version.driftWarning, version.alignmentCommand, pathExecutionHazard y capas (core, operational, integration, …) te dicen si estás mintiendo cuando dices “tenemos Pumuki”. Si driftWarning no es null, copia y pega el comando de alineación que el propio JSON te da; no improvises otro npx.

status --json: es la foto del menú/lifecycle y de la versión que el consumidor cree tener. Úsalo cuando alguien diga “en mi máquina funciona”: comparas status vs doctor y enseñas dónde miente la intuición.

install: reaplica hooks y lifecycle cuando algo los rompió (cambio de rama raro, copia de repo sin hooks, actualización de paquete).

2.4 pathExecutionHazard (la trampa del macOS con : en la ruta)

Si doctor marca pathExecutionHazard, muchos tutoriales de internet que dicen npx pumuki … te están perjudicando. El propio doctor suele sugerir un workaround del estilo:

node ./node_modules/pumuki/bin/pumuki.js install

Narrativa pedagógica: no es un bug de Pumuki; es la interacción entre shells, npx y rutas con caracteres que el runtime interpreta mal. El alumno debe asociar el síntoma (“command not found” o binario equivocado) con esta señal en JSON.

2.5 Primer gate manual (cierra el círculo)

Después de install y doctor razonablemente limpio, ejecuta explícitamente:

npx --yes --package pumuki@latest pumuki-pre-commit

o el binario equivalente que tu package.json exponga. Observa código de salida (0 vs 1) y abre .ai_evidence.json. Tu objetivo pedagógico es narrar en voz alta: “el hook corrió este stage, sobre este scope, y la evidencia dice esto”.

Ciclo de vida completo (desinstalar, remove, update --latest, diferencia frente a npm uninstall) está en 02-modulos/08-ciclo-de-vida-install-uninstall-actualizacion.md: haz esa unidad en la misma semana que esta si vas a enseñar retirada del producto, no lo pospongas.

2.6 OpenSpec (cuando enterprise lo exige)

Si tu perfil incluye SDD, antes de declarar victoria ejecuta:

npx --yes pumuki sdd status

Si falta @fission-ai/openspec en node_modules del consumidor, verás OPENSPEC_MISSING aunque tengas un openspec global en el PATH. Esa frase debe quedar grabada: Pumuki resuelve OpenSpec repo-local, no por PATH global.

Ejercicio

1. Guarda doctor --json en un fichero before.json.
2. Introduce un problema menor y reversible (por ejemplo desalinear versión en package.json sin lock, o quitar temporalmente un hook).
3. Vuelve a ejecutar doctor --json → after.json.
4. Escribe cinco frases explicando qué campo cambió y por qué eso importa operativamente.
5. Restaura el repo a estado sano.

Lectura

• docs/product/INSTALLATION.md — postinstall, CI, troubleshooting.
• docs/product/USAGE.md — “Run locally”, variables, troubleshooting.
• README.md — “5-Minute Quick Start”.

Unidad U3 — Ciclo de vida: instalar, actualizar y retirar Pumuki sin dejar basura

Objetivo observable

Al cerrar esta unidad demuestras, en un repo de laboratorio, la diferencia operativa entre: instalar el paquete npm, reaplicar hooks, alinear versión con update, y retirar el producto con remove / uninstall sin confundir qué queda en .git/hooks, .pumuki/ y package.json.

Prerrequisitos

• Unidad equivalente al módulo 2 (primer doctor y install coherentes).
• Haber leído qué hace el postinstall en docs/product/INSTALLATION.md.

Idea central

Pumuki no es solo una línea en dependencies. Deja estado: hooks gestionados, directorio .pumuki/, a veces evidencia y artefactos. npm uninstall pumuki borra la dependencia del manifiesto npm; no es el mismo acto que “este repo ya no gobierna con Pumuki”. Para eso el producto expone comandos explícitos de lifecycle.

No confundas

1. Tres verbos de “poner”

1. npm install --save-exact pumuki — Declaras dependencia fijada; el postinstall puede ejecutar pumuki install en contexto Git (ver INSTALLATION).
2. npx pumuki install (y variantes --with-mcp --agent=…) — Reaplica hooks y wiring sin reinstalar todo npm a mano.
3. npx pumuki bootstrap --enterprise --agent=codex (u otro agente) — Orquestación recomendada en greenfield: hooks, OpenSpec si falta, openspec/ mínimo, evidencia baseline, adapter, doctor --deep.

Pregunta de comprobación: ¿puedes explicar en voz alta qué hace cada uno sin decir “instala Pumuki” tres veces?

2. Tres verbos de “quitar” o “alinear”

1. npm uninstall pumuki — Solo quita el paquete npm según npm; no garantiza limpieza de hooks ni de .pumuki/.
2. npx pumuki uninstall --purge-artifacts — Retira hooks gestionados y puede purgar artefactos de evidencia no trackeados (según política documentada en USAGE); úsalo cuando quieras desmontar sin borrar el repo entero.
3. npx pumuki remove — Camino enterprise-safe: lifecycle cleanup antes del uninstall del paquete; es la respuesta cuando alguien dice “sacad Pumuki de este servicio”.

Secuencia mental: si alguien “solo hizo npm uninstall” y los hooks siguen llamando a pumuki-pre-commit, el fallo no es “magia”, es estado inconsistente.

3. Actualizar versión sin drift eterno

• npm update pumuki (o npm upgrade según tu npm) sube la dependencia según rangos; con --save-exact en cultura enterprise sueles pin y luego npm install pumuki@<versión> explícita.
• npx pumuki update --latest — Documentado en USAGE como actualizar dependencia a latest y reaplicar hooks; después siempre valida con doctor --json y status --json y usa version.alignmentCommand si el JSON te muestra drift.

4. Contrato de versión (status / doctor)

El bloque version en JSON (véase USAGE) existe para que dejes de discutir “en mi máquina”. Si aparece driftWarning, no improvises: ejecuta el alignmentCommand que el propio JSON te da.

Actividad guiada (lab)

1. Rama nueva training/lifecycle-pumuki.
2. Anota estado: git status, listado de .git/hooks relevantes, si existe .pumuki/.
3. Ejecuta pumuki doctor --json → guarda before.json.
4. Simula “mala desinstalación”: npm uninstall pumuki sin pumuki remove. Observa qué queda en hooks y carpetas.
5. Remedia con el comando correcto del producto para tu objetivo (volver a sano o retirar del todo).
6. doctor --json → after.json.
7. Escribe ocho líneas: qué cambió y qué lección le darías a un compañero.

Criterio de dominio (autoevaluación honesta)

• Puedo nombrar dos diferencias concretas entre npm uninstall pumuki y pumuki remove.
• Sé cuándo elegir uninstall --purge-artifacts frente a remove.
• Tras un bump de versión, mi rutina incluye doctor y no solo “ya hice npm install”.

Lectura canónica

• docs/product/INSTALLATION.md — postinstall, bootstrap, troubleshooting.
• docs/product/USAGE.md — sección “Lifecycle + SDD + Loop CLI (install / uninstall / remove / update …)” y bloque version en JSON.

Unidad U4 — Evidencia: qué se escribe, cuándo no, y cómo leer el veredicto

Objetivo observable

Tras esta unidad puedes abrir .ai_evidence.json, identificar versión 2.1, relacionar el stage que acabas de ejecutar con el scope evaluado, y explicar por qué a veces PRE_PUSH no reescribe el fichero aunque el gate haya calculado telemetría interna.

Prerrequisitos

• Módulo 1 (tabla de stages y scopes).
• Haber ejecutado al menos un pumuki-pre-commit o equivalente en el lab.

Idea central

La evidencia es el acta notarial del gate: mismo contrato que debe entender el humano, CI y (vía MCP) el agente. Si solo miras el código de salida del hook, estás leyendo el titular; el JSON es el cuerpo del auto.

No confundas

1. Dónde vive y qué versión manda

• Ruta canónica: .ai_evidence.json.
• version: "2.1" es la fuente de verdad del esquema; si no cuadra, los consumidores MCP pueden responder 404 al leer evidencia: no inventan datos.

Referencia profunda: docs/mcp/ai-evidence-v2.1-contract.md.

2. Qué mirar primero en un JSON real

1. operational_hints (si existen): human_summary_lines, requires_second_pass, desglose de reglas evaluadas frente a bloqueantes — acelera el “qué pasó” sin leer todo el árbol.
2. snapshot y metadatos de SDD si aplica (snapshot.sdd_metrics).
3. Cobertura: unevaluated_rule_ids, unsupported_auto_rule_ids — bloqueos de gobernanza sin un “finding bonito” de estilo.
4. telemetry.chain cuando el flujo enlaza SDD + AI Gate (p. ej. PRE_WRITE en políticas que lo documenten).

3. PRE_COMMIT: restage de evidencia trackeada

Si el fichero está versionado y tras un gate no bloqueante el hook refresca el snapshot, Pumuki puede volver a hacer git add de la evidencia salvo que el índice (ignorando los paths de evidencia) sea solo documentación (.md, .mdx). Entonces el archivo se actualiza en disco pero no entra solo en el commit; verás aviso [pumuki][evidence-sync] en stderr si no está silenciado. Variable de escape: PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE=1 (CONFIGURATION).

Pedagogía: esto explica tickets del tipo “el hook tocó el archivo pero no está en el commit”.

4. PRE_PUSH: por qué “no cambió el archivo”

Con evidencia trackeada y outcome PASS/WARN, puede no reescribirse .ai_evidence.json para no romper cadenas de pre-commit/pre-push. Forzar escritura: PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1 (consciente de las implicaciones que describe USAGE).

Actividad guiada (lab)

1. Copia de seguridad: cp .ai_evidence.json /tmp/evidence.backup.json (si existe).
2. Ejecuta PRE_COMMIT con cambios staged mínimos; guarda el JSON resultante como after-precommit.json.
3. Sin commitear aún (si tu política lo permite) o en otra rama, ejecuta PRE_PUSH o el flujo que uses; compara timestamps y contenido de .ai_evidence.json con lo aprendido en §3–§4.
4. Anota en tres frases qué parte del JSON demuestra el scope evaluado.

Criterio de dominio

• Explico en una frase la política de no escritura en PRE_PUSH con archivo trackeado.
• Localizo en JSON al menos un campo de cobertura de reglas y sé si implica BLOCK.
• Sé dónde buscar human_summary_lines antes de abrir el ledger completo.

Lectura canónica

• docs/product/USAGE.md — “Evidence output”, subsecciones PRE_COMMIT / PRE_PUSH / PRE_WRITE.
• docs/mcp/ai-evidence-v2.1-contract.md.

Módulo 3 — Perfiles de adopción

3.1 Por qué “perfil” no es snobismo

Un perfil es el paquete de dolor y beneficio que tu organización acepta. Pumuki permite ir de mínimo (hooks que protegen sin abrir todo el paraguas enterprise) a enterprise completo (SDD obligatorio, skills lock, MCP, parity, policy-as-code). El error típico es instalar enterprise y comportarse como si fueras mínimo: nadie abre sesión SDD, nadie mira doctor, y el equipo odia “la herramienta” en lugar de su propio incumplimiento.

Este módulo te da lenguaje para negociar con tech lead y seguridad: qué compras y qué vendes en cada nivel.

3.2 Perfil mínimo (hooks + evidencia baseline)

Qué suele incluir: dependencia pumuki, hooks PRE_COMMIT / PRE_PUSH (y en versiones recientes cadena con PRE_WRITE según configuración), reglas core embebidas, evidencia v2.1 cuando el gate corre.

Qué no garantiza: que OpenSpec esté sano, que skills custom estén cerrados, que CI y laptop sean idénticos, que MCP exista.

Cuándo tiene sentido: equipos pequeños, repos de biblioteca interna, fase de prueba antes de enterprise.

Riesgo pedagógico: el equipo cree que “ya tenemos gobernanza” cuando solo tienen un subconjunto de reglas. Debes documentar en el repo qué perfil sois.

3.3 Perfil estándar (SDD / OpenSpec)

Qué añade: comandos pumuki sdd …, validación por stage, bloqueos con códigos OPENSPEC_ y SDD_. El flujo mental del desarrollador debe incluir “¿tengo cambio activo?” antes de pedir merge.

Qué no sustituye: el método SDD que enseña el curso de IA + SDD. Pumuki enciende el semáforo; no escribe tus specs.

Cuándo tiene sentido: equipos que ya usan OpenSpec o están migrando con disciplina.

3.4 Perfil enterprise completo

Qué añade típicamente: bootstrap --enterprise, skills.lock.json y reglas custom, MCP (evidence + enterprise), pumuki doctor --parity, notificaciones y hard mode donde aplique, policy-as-code en .pumuki/policy-as-code.json si vuestra auditoría lo pide.

Qué exige al equipo: operar el sistema: leer JSON de doctor, entender recibos MCP en PRE_WRITE cuando la política los exija, mantener parity CI.

Frase para el alumno: “Enterprise no es instalar más paquetes; es aceptar más obligaciones de comportamiento.”

3.5 Tabla de decisión (úsala en el lab)

Ejercicio

En el README del lab (o CONTRIBUTING.md), escribe un párrafo que declare:

1. Perfil elegido (mínimo / estándar SDD / enterprise).
2. Un riesgo concreto de bajar un nivel (por ejemplo: “si pasamos a mínimo, perdemo validación SDD en PRE_PUSH”).
3. Un comando que el equipo promete ejecutar en onboarding (doctor --json o sdd status).

Compártelo con un compañero: si no entiende el párrafo en una lectura, reescribe.

Lectura

• README.md del producto — tabla “Rutas de adopción”.
• docs/product/USAGE.md — feature flags y menú.
• docs/product/CONFIGURATION.md — hard mode y policy cuando escaléis.

Módulo 4 — SDD y Pumuki

4.1 Dos capas que no debes fusionar

SDD / OpenSpec responde: “¿Este cambio está bien gobernado como cambio — existe, está abierto, no está archivado, pasa validación?”

Pumuki (gate) responde: “¿Este código en este scope cumple reglas y evidencia en este stage?”

Cuando Pumuki bloquea con SDD_SESSION_MISSING, no está juzgando tu arquitectura: está diciendo “según la política enterprise, no hay sesión de cambio que amarre este trabajo”. La remedición es operativa (abrir sesión, refrescar, validar), no “quitar Pumuki”.

4.2 Variable experimental y política

El producto documenta PUMUKI_EXPERIMENTAL_SDD y comandos bajo pumuki sdd …. Pedagógicamente:

• Experimental no significa “juguete”; significa “tu organización elige activar este namespace con consciencia”.
• Cuando está activo, debes enseñar el día a día: sdd status, sdd session --open --change=<id>, sdd validate --stage=PRE_COMMIT (y otros stages según vuestro runbook).

4.3 Catálogo de códigos que el alumno sí debe reconocer

No hace falta memorizarlos todos; hace falta clasificarlos:

Tarea de aula: pegar una salida JSON real (sin secretos) y etiquetar cada código con “acción humana siguiente” en una frase.

4.4 PRE_WRITE y el recibo MCP (cuando aplique)

En políticas enterprise, PRE_WRITE puede enlazar gate + evidencia + recibo MCP (mcp-ai-gate-receipt.json). La narrativa para el alumno:

1. El agente (o tú) ejecuta ai_gate_check vía MCP enterprise.
2. El producto persiste recibo auditable.
3. pumuki sdd validate --stage=PRE_WRITE puede bloquear si el recibo falta o está stale (MCP_ENTERPRISE_RECEIPT_*).

Esto es diseño anti-vapor: no basta con decir “la IA prometió que lo revisó”; debe quedar artefacto verificable. Si tu equipo no usa agentes, puede que no activéis este enforcement; si lo activáis, debe formar parte del onboarding.

4.5 Dónde profundiza el playbook del curso

El documento docs/playbook-pumuki-sdd-bridge.md en este repo del curso enlaza rituales de equipo (quién abre cambio, cuándo se valida, qué hace el agente). Léelo después de este módulo si vas a diseñar proceso, no antes de saber qué es un stage.

4.6 Flujo diario mínimo (orden que debe automatizar el cerebro)

Objetivo observable: en un día normal puedes decir los comandos en secuencia sin mezclar “validar” con “commitear”.

1. Inspección: npx --yes pumuki sdd status — foto de OpenSpec/sesión.
2. Apertura o continuidad de cambio: pumuki sdd session --open --change=<id> (y --refresh en sesiones largas si vuestro runbook lo pide).
3. Validación explícita por stage cuando dudes: pumuki sdd validate --stage=PRE_COMMIT (o PRE_PUSH / PRE_WRITE según el punto del flujo).
4. Gate real del repo: pumuki-pre-commit / pumuki-pre-push / hook CI — es otro paso; SDD puede bloquear antes de que el gate mire reglas de código.

Pregunta de aula: ¿en qué paso de la lista anterior un compañero suele saltarse la sesión y luego culpa al “gate de reglas”?

4.7 Síntoma clásico: OPENSPEC_MISSING con openspec --version OK en la terminal

No confundas: Pumuki resuelve OpenSpec solo desde el repo bajo chequeo: node_modules/.bin/openspec. Un openspec instalado con Homebrew o en otro PATH no cuenta.

Secuencia de remediación pedagógica:

1. Comprueba que @fission-ai/openspec está en dependencies / devDependencies del consumidor (bootstrap o npm install según INSTALLATION).
2. Verifica que existe ./node_modules/.bin/openspec en la raíz del repo (no en el home).
3. Vuelve a pumuki sdd status y pumuki doctor --deep --json.

Si enseñas esto antes del primer bloqueo, ahorras horas de “en mi terminal funciona”.

4.8 PRE_WRITE: sobre JSON y cadena pumuki->ai_gate->ai_evidence

pumuki sdd validate --stage=PRE_WRITE --json devuelve un sobre con, entre otros:

• sdd — decisión de política SDD.
• ai_gate — evaluación AI Gate (incluye skills_contract cuando aplica).
• telemetry.chain — literalmente la cadena que enlaza ejecución y evidencia.

Actividad corta: ejecuta el comando en el lab (si tu política lo permite), imprime JSON y subraya esos tres nodos. Si PRE_WRITE está desactivado en vuestro perfil, haz el ejercicio en lectura sobre un JSON anonimizado que traiga el instructor.

Criterio de dominio (unidad U7, SDD)

• Clasifico OPENSPEC_MISSING frente a SDD_SESSION_MISSING sin abrir el código fuente de Pumuki.
• Recito el flujo 4.6 en orden correcto.
• Sé qué buscar en el JSON de PRE_WRITE para explicar “SDD vs AI Gate” a un tech lead.

Ejercicio

1. Crea un change-id ficticio training/pumuki-01 en el lab (siguiendo la convención de vuestro OpenSpec).
2. Ejecuta pumuki sdd session --open --change=training/pumuki-01 (o el comando equivalente de vuestra versión).
3. Ejecuta pumuki sdd validate --stage=PRE_COMMIT --json y resalta en el JSON: sdd, telemetry.chain si aparece, y cualquier bloqueo.
4. Escribe qué cerraría el loop de verificación en un ticket real (una frase por campo bloqueante).

Lectura

• docs/product/USAGE.md — “Mandatory SDD/OpenSpec flow”, códigos listados.
• docs/playbook-pumuki-sdd-bridge.md — puente operativo.
• Curso IA + SDD del hub — método Kanban y cierre de cambio.

Unidad U5 — Menú interactivo: Consumer, Advanced, matrix y pre-flight

Objetivo observable

Puedes lanzar pumuki-framework en un consumidor, explicar la diferencia entre modo Consumer y Advanced, mapear las opciones 1 / 2 / 3 / 4 a stage y scope, y describir qué aporta la matrix no interactiva frente al menú TUI.

Prerrequisitos

• Módulo 1 (PRE_COMMIT vs PRE_PUSH, scopes).
• Node/npm funcionando en el repo lab.

Idea central

El menú es un panel de mandos humano sobre el mismo motor que los hooks. No redefine la política: la hace legible y ejecutable sin memorizar flags. Las opciones 1–4 son el núcleo legible en Consumer; Advanced añade diagnósticos y legado read-only que no debes confundir con “la verdad del gate” en CI.

No confundas

1. Cómo arrancarlo

Consumidor:

npx --yes --package pumuki@latest pumuki-framework

Repositorio framework (mantenedores del paquete):

npm run framework:menu

Modo Advanced desde el primer momento:

PUMUKI_MENU_MODE=advanced npm run framework:menu

Renderer: PUMUKI_MENU_UI_V2=0 clásico, PUMUKI_MENU_UI_V2=1 agrupado con badges; si v2 falla, hay fallback a clásico.

Ruta del consumidor estable (evita prompts raros por cwd):

export PUMUKI_CONSUMER_REPO_PATH=/ruta/absoluta/al/repo

2. Consumer: qué enseñar el primer día

• A — alterna Advanced; C — vuelve a Consumer.
• 1 / 2 / 3 / 4 — flujos read-only alineados con gates; mapeo típico (USAGE):
• 1 → PRE_COMMIT, scope repo
• 2 → PRE_PUSH, repo + staged
• 3 → PRE_COMMIT, staged
• 4 → PRE_PUSH, working tree
• 8 — export markdown del snapshot de evidencia.
• 5 / 6 / 7 / 9 — USAGE las agrupa como Legacy Read-Only Diagnostics en Consumer; trátalas como taller de forense, no como checklist de release.

3. Pre-flight antes del gate en 1–4

Antes de ejecutar el gate, el menú puede evaluar: estado Git (rama, upstream, sucio), consistencia cadena pumuki → mcp → ai_gate → ai_evidence, señales de evidencia stale/missing/invalid, violaciones GitFlow en ramas protegidas. Si el scope está vacío, debe mostrar pista explícita (Scope vacío) para no confundir PASS vacío con “repo limpio escaneado”.

4. Matrix no interactiva (determinismo en CI o scripts)

USAGE documenta el consumer menu matrix vía node --import tsx importando framework-menu-matrix-runner-lib.ts: produce JSON con byOption por 1,2,3,4,9 y diagnósticos scope-empty|repo-clean|violations-detected|unknown.

Cuándo enseñarlo: a equipos que necesitan regresión del menú sin TUI, o que automatizan “mismo menú que el humano”.

Actividad guiada (lab)

1. Arranca pumuki-framework en el repo lab.
2. En Consumer, ejecuta una opción de 1–4 y anota: stage impreso, scope, código de salida.
3. Cambia a Advanced, localiza una opción de toolkit o legacy y explica por qué no la usarías para decidir release.
4. (Opcional) Ejecuta la matrix documentada en USAGE y conserva el JSON en .audit-reports/ local (sin subir secretos).

Criterio de dominio

• Dibujo en una servilleta el mapeo 1–4 → stage + scope sin mirar el manual.
• Explico la diferencia entre opción 8 y ejecutar pumuki-pre-commit.
• Sé para qué sirve PUMUKI_CONSUMER_REPO_PATH.

Lectura canónica

• docs/product/USAGE.md — “Interactive menu”, “Non-interactive consumer matrix”, “Consumer pre-flight”.
• docs/operations/framework-menu-consumer-walkthrough.md — recorrido visual opción 1.

Unidad U6 — MCP: enforcement frente a lectura, HTTP, stdio y recibo PRE_WRITE

Objetivo observable

Explicas sin titubeos: por qué los hooks y CI pueden pasar aunque no haya ningún servidor MCP levantado; qué diferencia hay entre pumuki-mcp-evidence y pumuki-mcp-enterprise; y en qué situación un recibo bajo .pumuki/artifacts/ forma parte del cierre PRE_WRITE en políticas enterprise.

Prerrequisitos

• Unidad U4 (evidencia en disco).
• Módulo 4 (SDD y PRE_WRITE a alto nivel).

Idea central

MCP es una superficie de interoperabilidad para IDEs y agentes: leer estado, exponer tools con guardrails, a veces participar en cadenas documentadas (p. ej. AI Gate + recibo). No es el motor del gate en pre-commit / pre-push / ci: ese motor vive en el paquete y en Git.

No confundas

1. Servidores y puentes (mapa mínimo)

Según docs/mcp/mcp-servers-overview.md:

Arranque consumidor típico:

npx --yes --package pumuki@latest pumuki-mcp-evidence
npx --yes --package pumuki@latest pumuki-mcp-enterprise
npx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio

Variables de host/puerto: PUMUKI_EVIDENCE_, PUMUKI_ENTERPRISE_MCP_ (incl. puerto 0 para efímero si EADDRINUSE).

2. Qué resuelve pumuki install vs --with-mcp

El postinstall puede crear .pumuki/adapter.json con líneas de comando stdio genéricas; no sustituye pumuki install --with-mcp --agent=codex (o el agente que uses) cuando quieres scaffolding alineado al IDE y resumen de salud MCP al finalizar (INSTALLATION / USAGE).

3. Tools experimentales y ai_gate_check

En enterprise MCP, tools como ai_gate_check, pre_flight_check, auto_execute_ai_start pueden listarse solo si activas el feature experimental documentado (PUMUKI_EXPERIMENTAL_MCP_ENTERPRISE=advisory|strict, etc.).

ai_gate_check persiste recibo en .pumuki/artifacts/mcp-ai-gate-receipt.json para trazabilidad PRE_WRITE cuando tu política lo exige.

4. Cadena que el alumno debe poder dibujar

telemetry.chain = "pumuki->ai_gate->ai_evidence" aparece en validaciones PRE_WRITE cuando aplica: no es adorno; conecta SDD + AI Gate + evidencia en un solo sobre JSON (pumuki sdd validate --stage=PRE_WRITE --json).

Actividad guiada (lab)

1. Abre .pumuki/adapter.json (si existe) y localiza las líneas stdio propuestas; no pegues secretos en el aula.
2. Sin levantar HTTP, razona: “¿mi IDE usaría stdio o HTTP?” y apunta la evidencia en la doc.
3. Lee GET /health o equivalente solo si tu política de seguridad lo permite en local; si no, limita el ejercicio a lectura de documentación y diagrama en pizarra.

Criterio de dominio

• Distingo enforcement de superficie MCP en dos frases.
• Nombro dos binarios MCP y su uso típico (evidence vs enterprise).
• Sé qué archivo de recibo cita el módulo SDD para PRE_WRITE y cuándo aplica.

Lectura canónica

• docs/mcp/mcp-servers-overview.md
• docs/product/USAGE.md — MCP health en install, PRE_WRITE envelope, experimental tools.
• docs/product/INSTALLATION.md — adapter scaffolding.

Unidad U8 — Notificaciones (macOS / stderr) y pumuki watch

Objetivo observable

Configuras o explicas el canal de notificación que usa Pumuki en tu OS: persistencia en .pumuki/system-notifications.json, variables para stderr y espejo, comportamiento del modal de bloqueo en macOS, y usas pumuki watch en modo seguro (--once o iteraciones) para vigilancia local sin spam.

Prerrequisitos

• Unidad U5 (menú: opción 31 activa notificaciones desde Advanced).
• Saber qué stage te interesa vigilar (normalmente PRE_COMMIT en iteración).

Idea central

Las notificaciones no cambian la política del gate: informan y reducen sorpresa cuando un bloqueo ocurre en contexto IDE/terminal. En plataformas sin API de banner, el producto cae a stderr por defecto para no perder señal. watch reevalúa política ante cambios locales y puede notificar con umbral de severidad y cooldown anti-spam.

No confundas

1. Activación desde el menú

Advanced → opción 31 escribe configuración en .pumuki/system-notifications.json. En macOS revisa permisos del terminal en Ajustes del sistema → Notificaciones.

2. Variables de entorno que el soporte pregunta a diario

• PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1 — Sin stderr en plataformas sin banner.
• PUMUKI_NOTIFICATION_STDERR_MIRROR=1 (macOS) — Duplica cualquier payload a stderr además del banner.
• gate.blocked en macOS — Espejo stderr por defecto cuando el banner macOS informa éxito; cortar solo eso: PUMUKI_DISABLE_GATE_BLOCKED_STDERR_MIRROR=1.
• PUMUKI_MACOS_BLOCKED_DIALOG_MODE=auto|swift-floating|applescript — Override del renderer del modal.

3. pumuki watch — patrón seguro para formación

Ejemplo USAGE (ajusta rutas y política):

npx --yes pumuki watch --stage=PRE_COMMIT --scope=workingTree --severity=high --interval-ms=3000 --notify-cooldown-ms=30000

• --no-notify — Salida terminal sin OS notifications.
• --once o --iterations=n — Para scripts y demos; evita dejar procesos colgados en el lab.
• --json — Incluye trazas útiles (lastTick.changedFiles, lastTick.evaluatedFiles).

Higiene: el producto puede auto-excluir artefactos en .git/info/exclude para no ensuciar el worktree (USAGE).

Actividad guiada (lab)

1. En macOS: activa notificaciones vía menú 31, provoca un BLOCK conocido (p. ej. regla que controles) y observa banner + stderr según variables.
2. En no-macOS: ejecuta el mismo escenario y documenta qué ves en stderr; prueba PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1.
3. Ejecuta pumuki watch --once --json y conserva el JSON sin secretos para discusión en equipo.

Criterio de dominio

• Ubico system-notifications.json y sé qué hace blockedDialogEnabled.
• Explico la diferencia entre severidad de notify y bloqueo del gate.
• No dejo watch infinito corriendo en CI sin documentación.

Lectura canónica

• docs/product/USAGE.md — párrafo de system notifications tras “Consumer pre-flight”, sección Watch runtime behavior.
• docs/operations/framework-menu-consumer-walkthrough.md — contexto UX menú.

Módulo 5 — Governance y Pumuki

5.1 Dos fuentes de verdad que deben convivir

Governance (AGENTS.md, skills, GitFlow acordado, revisión humana) responde: “¿Qué debe hacer un equipo disciplinado y cómo decide?”

Pumuki responde: “¿Lo que está en el diff cumple lo que ya bajó a reglas evaluables y versionadas?”

Si intentas que Pumuki reemplace el README de cultura del equipo, fracasarás: Pumuki no lee la intención en vuestros corazones; lee locks, custom rules, hechos y políticas.

5.2 De AGENTS.md al gate (sin duplicar el documento)

AGENTS.md suele ser normativo para humanos y agentes (“no hagas force push”, “usa estas skills”). Pumuki no parsea AGENTS.md como única fuente de reglas en todos los modos; lo que sí hace es alinear el gate con skills materializadas en skills.lock.json y reglas AUTO/DECLARATIVE según el motor de skills.

Narrativa pedagógica: cuando una regla “está en AGENTS” pero no está en el lock efectivo, el gate puede no verla. El trabajo de governance es bajar la política a artefactos que el motor entienda.

5.3 GitFlow y ramas protegidas en el lenguaje del alumno

Los hooks recientes pueden aplicar git-flow (GITFLOW_PROTECTED_BRANCH) e higiene de worktree junto al gate cuando la evidencia es válida. Eso significa:

• No es solo “lint falló”: puede ser “estás en develop y tu política dice que no tocas X sin Y”.
• El mensaje del gate debe leerse como texto contractual, no como ataque personal.

Ejercicio de lectura: busca en docs/product/USAGE.md y en mensajes de pumuki-pre-push referencias a upstream, tracking, rama protegida. Escribe una analogía con “permiso de aeropuerto” (sin equipaje documentado no pasas) — ayuda a equipos no técnicos a entender por qué el push falló.

5.4 Remediaciones y operational_hints

Cuando el producto expone remediaciones u hints en JSON, el equipo de governance debe revisar si están alineados con el runbook interno. Si el hint dice “ejecuta X” y vuestro runbook dice “nunca X en producción”, actualizáis runbook o ajustáis política — no ignoráis la contradicción.

5.5 Skills: precedencia y conflicto

Orden mental: core (embebido) → repo (skills.lock.json) → custom (.pumuki/custom-rules.json), con custom > repo > core por ruleId.

Conflicto no es emergencia: es decisión ya tomada por diseño. El alumno debe saber dónde mirar cuando dos documentos humanos contradicen el gate: el lock efectivo.

Ejercicio

1. Elige dos reglas que en vuestro equipo “viven” en skills o AGENTS (por ejemplo naming, capas, prohibición de patrón).
2. Para cada una, indica: ¿está en skills.lock.json o custom rules con ruleId identificable?
3. Provoca un fallo reproducible mínimo en el lab que dispare una de ellas.
4. Pega el finding correspondiente de .ai_evidence.json (redacta secretos) y narra la cadena fact → rule → decisión.

Lectura

• docs/product/USAGE.md — mensajes, stages, hints.
• README.md del producto — “Rules resolution order”.
• Curso Governance del hub — quality gates y kit.
• AGENTS.md de vuestro repo consumidor.

Módulo 6 — Monorepo, CI y parity

6.1 Por qué el monorepo rompe la cabeza sin scope

En un monorepo, no todo el árbol pertenece al mismo producto ni a la misma política. Si Pumuki evalúa todo el repo en cada commit de un paquete pequeño, obtienes ruido (findings en carpetas que tu equipo ni mira) o bloqueos injustos.

La válvula documentada en el producto pasa por PUMUKI_GATE_SCOPE_PATH_PREFIXES: una lista de prefijos de ruta que delimitan dónde el gate debe gastar CPU y política. Pedagógicamente, es el equivalente a decir: “la inspección solo entra en estas habitaciones”.

6.2 Qué debe hacer el alumno mentalmente antes de configurar prefijos

1. Listar paquetes o apps que comparten repo pero no comparten release.
2. Decidir si comparten mismo skills.lock.json o locks por paquete (si aplica).
3. Probar un commit que solo toca fuera del prefijo y verificar que el gate no inventa findings fuera de scope (o que los trata según política explícita — lo importante es predecibilidad).

6.3 Parity: laptop vs CI

pumuki doctor --parity existe para comparar el mundo local con expectativas de CI cuando vuestro equipo versiona un contrato en .pumuki/ci-parity-expected.json. No es obligatorio en todos los repos; es herramienta para equipos que ya se quemaron con “en CI falla y en mi máquina no”.

Narrativa: parity no arregla bugs; acota dónde diverge el entorno (versión, bins, flags, rutas).

6.4 CI sin GitHub Actions (u otros)

Aunque tu organización no tenga minutos de Actions, el concepto de stage CI sigue existiendo: cualquier job que ejecute pumuki-ci con un rango base..HEAD válido es CI para Pumuki. Enseña el contrato del runner: no HEAD..HEAD ambiguo, contexto de merge request correcto, mismas variables de prefijo que en local.

Ejercicio

1. Si tu lab no es monorepo, simula dos carpetas packages/a y packages/b con un archivo cada una.
2. Configura prefijos para que solo packages/a esté en scope (siguiendo la sintaxis de USAGE.md para tu versión).
3. Haz un commit que solo toque packages/b y ejecuta el gate que corresponda: documenta si hubo findings y por qué (o por qué no).
4. Opcional: ejecuta doctor --parity si tenéis ci-parity-expected.json; si no, redacta qué pondrías en ese fichero la primera semana de adopción.

Lectura

• docs/product/USAGE.md — variables de scope y parity.
• CHANGELOG.md del producto — cambios recientes en gate scope / parity.
• README.md — línea PUMUKI_GATE_SCOPE_PATH_PREFIXES si aparece en tabla de features.

Módulo 7 — Proyecto final y checklist de release

7.1 Qué demuestras con este cierre

No es un examen de trivia. Es prueba de que puedes operar Pumuki en un repo real: instalar, diagnosticar, enlazar SDD/Governance cuando aplique, y explicar el resultado a otra persona sin mirar el teléfono.

7.2 Checklist mínima (todos los perfiles)

Marca solo cuando tengas evidencia (comando, log, JSON, captura de política interna).

1. Versión fijada — pumuki en package.json con política de equipo (exact recomendado).
2. doctor --json sin bloqueos críticos para vuestro estándar (documentáis qué capa aceptáis en WARN).
3. status --json alineado con doctor (no drift silencioso).
4. Hooks — pre-commit / pre-push (y pre-write si aplica) ejecutan los bins documentados en adapter.json o runbook.
5. Evidencia — existe .ai_evidence.json v2.1 válida después de un gate completo; sabes leer al menos findings y snapshot.rules_coverage a alto nivel.
6. Runbook de 1 página — qué hacer cuando falla un hook (orden: leer mensaje → doctor → sdd validate si enterprise → escalar).

7.3 Checklist ampliada (perfil SDD)

1. OpenSpec resuelto repo-local (node_modules/.bin/openspec o dependencia documentada).
2. pumuki sdd status entendido por dos personas del equipo distintas del autor del curso.
3. Sesión de cambio — flujo --open / --refresh documentado para vuestra convención de change-id.
4. Validación por stage — tabla interna: “antes de MR ejecutamos validate --stage=…”.

7.4 Checklist ampliada (perfil enterprise)

1. MCP — decidido si usáis evidence HTTP, enterprise HTTP, stdio, o ninguno; documentado el porqué.
2. Tools experimentales — si activáis PUMUKI_EXPERIMENTAL_MCP_ENTERPRISE, quién puede invocar validate_and_fix y bajo qué SDD session.
3. PRE_WRITE + recibo — si política lo exige, dónde se guarda el recibo y cuánto dura “fresco”.
4. doctor --parity o plan explícito de por qué no lo usáis aún.
5. Monorepo — prefijos de scope revisados por owners de cada paquete.

7.5 Entrega sugerida

Sube a vuestro sistema de gestión (o al README del lab):

• Enlace al commit donde el checklist quedó verde.
• doctor --json final (sin secretos).
• Un párrafo de retro: “qué fue lo más confuso y cómo lo resolvimos”.

Referencias de auditoría del curso

• docs/AUDIT-AND-RELEASE.md — proceso de validación del material del curso en el repo stack-my-architecture-pumuki.
• docs/tracking/plan-curso-pumuki-stack-my-architecture.md — en el repo ast-intelligence-hooks (seguimiento de la iniciativa formativa).

Cierre

Si llegaste aquí y aún sientes que “el README del producto tiene más carne”, bien: el README debe seguir siendo la fuente máxima. Lo que este curso te debía dar —y ahora sí pretende dar— es orden narrativo, mapa mental y ejercicios para que ese README no te aplaste. Vuelve a 02-modulos/00-mapa-completo-del-producto.md cuando necesites recolocarte.