pumuki 6.3.71 → 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,13 @@ 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.

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`).
@@ -565,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.
@@ -806,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/git/GitService.ts

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

package/integrations/git/runPlatformGateFacts.ts

@@ -19,6 +19,10 @@ export type GateScope =
     kind: 'workingTree';
     extensions?: string[];
   }
+  | {
+    kind: 'unstaged';
+    extensions?: string[];
+  }
   | {
     kind: 'range';
     fromRef: string;
@@ -66,6 +70,9 @@ export const resolveFactsForGateScope = async (params: {
   if (params.scope.kind === 'workingTree') {
     return params.git.getStagedAndUnstagedFacts(extensions);
   }
+  if (params.scope.kind === 'unstaged') {
+    return params.git.getUnstagedFacts(extensions);
+  }
 
   return getFactsForCommitRange({
     fromRef: params.scope.fromRef,

package/integrations/mcp/preFlightCheck.ts

@@ -4,7 +4,8 @@ import { resolveLearningContextExperimentalFeature } from '../policy/experimenta
 import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING: 'Ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
+  EVIDENCE_MISSING:
+    'Ejecuta una auditoría (1/2/3/4 u opciones de motor 11–14) para regenerar .ai_evidence.json.',
   EVIDENCE_INVALID: 'Regenera .ai_evidence.json desde una opción de auditoría.',
   EVIDENCE_INTEGRITY_MISSING: 'Refresca evidencia para regenerar metadatos de integridad.',
   EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:

package/integrations/sdd/openSpecCli.ts

@@ -17,20 +17,29 @@ type OpenSpecCommandResult = {
   stderr: string;
 };
 
-const resolveOpenSpecBinary = (repoRoot: string): string => {
+const resolveOpenSpecBinary = (repoRoot: string): string | undefined => {
   const binaryName = process.platform === 'win32' ? 'openspec.cmd' : 'openspec';
   const localBinaryPath = join(repoRoot, 'node_modules', '.bin', binaryName);
   if (existsSync(localBinaryPath)) {
     return localBinaryPath;
   }
-  return 'openspec';
+  return undefined;
 };
 
 const runOpenSpecCommand = (
   args: ReadonlyArray<string>,
   cwd: string
 ): OpenSpecCommandResult => {
-  const result = runSpawnSync(resolveOpenSpecBinary(cwd), [...args], {
+  const binary = resolveOpenSpecBinary(cwd);
+  if (!binary) {
+    return {
+      exitCode: 127,
+      stdout: '',
+      stderr:
+        'OpenSpec CLI not found under repo node_modules/.bin (add @fission-ai/openspec to this repository).',
+    };
+  }
+  const result = runSpawnSync(binary, [...args], {
     cwd,
     encoding: 'utf8',
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.71",
+  "version": "6.3.72",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {
@@ -259,10 +259,13 @@
     "docs/product/*.md",
     "docs/rule-packs/*.md",
     "docs/validation/*.md",
+    "docs/tracking/plan-curso-pumuki-stack-my-architecture.md",
     "assets/**/*",
     "vendor/skills/**/*",
     "index.js",
     "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
     "LICENSE",
     "VERSION",
     "tsconfig.json",

package/scripts/consumer-menu-matrix-baseline-report-lib.ts

@@ -4,10 +4,11 @@ import type {
   ConsumerMenuMatrixReport,
   MatrixOptionId,
 } from './framework-menu-matrix-baseline-lib';
+import { MATRIX_MENU_OPTION_IDS } from './framework-menu-matrix-evidence-lib';
 import type { DoctorDeepCheckLayer, LifecycleDoctorReport } from '../integrations/lifecycle/doctor';
 import type { LifecycleStatus } from '../integrations/lifecycle/status';
 
-const OPTION_IDS: ReadonlyArray<MatrixOptionId> = ['1', '2', '3', '4', '9'];
+const OPTION_IDS: ReadonlyArray<MatrixOptionId> = [...MATRIX_MENU_OPTION_IDS];
 const DOCTOR_LAYERS: ReadonlyArray<DoctorDeepCheckLayer> = [
   'core',
   'operational',
@@ -51,45 +52,19 @@ export type ConsumerMenuMatrixBaselineSnapshot = {
   };
 };
 
+const UNKNOWN_OPTION_REPORT = {
+  stage: 'UNKNOWN',
+  outcome: 'UNKNOWN',
+  filesScanned: 0,
+  totalViolations: 0,
+  diagnosis: 'unknown' as const,
+};
+
 const buildEmptyRound = (): ConsumerMenuMatrixReport => {
   return {
-    byOption: {
-      '1': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '2': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '3': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '4': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '9': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-    },
+    byOption: Object.fromEntries(
+      MATRIX_MENU_OPTION_IDS.map((id) => [id, { ...UNKNOWN_OPTION_REPORT }])
+    ) as ConsumerMenuMatrixReport['byOption'],
   };
 };
 

package/scripts/framework-menu-consumer-actions-lib.ts

@@ -9,6 +9,10 @@ export type ConsumerLegacyMenuContext = {
   runStrictRepoAndStaged: () => Promise<void>;
   runStrictStagedOnly: () => Promise<void>;
   runStandardCriticalHigh: () => Promise<void>;
+  runEngineStagedNoPreflight: () => Promise<void>;
+  runEngineUnstagedNoPreflight: () => Promise<void>;
+  runEngineStagedAndUnstagedNoPreflight: () => Promise<void>;
+  runEngineFullRepoNoPreflight: () => Promise<void>;
   runPatternChecks: () => Promise<void>;
   runEslintAudit: () => Promise<void>;
   runAstIntelligence: () => Promise<void>;
@@ -22,24 +26,44 @@ export const createConsumerLegacyMenuActions = (
   return [
     {
       id: '1',
-      label: 'Read-only full audit (repo analysis · PRE_COMMIT)',
+      label: 'Consumer preflight + gate: ALL tracked files (PRE_COMMIT · writes evidence)',
       execute: params.runFullAudit,
     },
     {
       id: '2',
-      label: 'Read-only strict REPO+STAGING (CI/CD · PRE_PUSH)',
+      label: 'Consumer preflight + gate: REPO+index contract (PRE_PUSH · disk skip risk if evidence tracked)',
       execute: params.runStrictRepoAndStaged,
     },
     {
       id: '3',
-      label: 'Read-only strict STAGING only (dev · PRE_COMMIT)',
+      label: 'Consumer preflight + gate: STAGED only (PRE_COMMIT)',
       execute: params.runStrictStagedOnly,
     },
     {
       id: '4',
-      label: 'Read-only audit of STAGED+UNSTAGED working tree (PRE_PUSH policy)',
+      label: 'Consumer preflight + gate: working tree (PRE_PUSH policy · disk skip risk if evidence tracked)',
       execute: params.runStandardCriticalHigh,
     },
+    {
+      id: '11',
+      label: 'Engine audit · STAGED only (no preflight · PRE_COMMIT)',
+      execute: params.runEngineStagedNoPreflight,
+    },
+    {
+      id: '12',
+      label: 'Engine audit · UNSTAGED only (no preflight · PRE_COMMIT)',
+      execute: params.runEngineUnstagedNoPreflight,
+    },
+    {
+      id: '13',
+      label: 'Engine audit · STAGED + UNSTAGED (no preflight · PRE_COMMIT)',
+      execute: params.runEngineStagedAndUnstagedNoPreflight,
+    },
+    {
+      id: '14',
+      label: 'Engine audit · FULL tracked repo (no preflight · PRE_COMMIT)',
+      execute: params.runEngineFullRepoNoPreflight,
+    },
     {
       id: '5',
       label: 'Legacy read-only pattern checks snapshot',

package/scripts/framework-menu-consumer-preflight-hints.ts

@@ -7,7 +7,8 @@ import type {
 } from './framework-menu-consumer-preflight-types';
 
 export const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING: 'ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
+  EVIDENCE_MISSING:
+    'ejecuta una auditoría (1/2/3/4 o motor 11–14) para regenerar .ai_evidence.json.',
   EVIDENCE_INVALID: 'regenera .ai_evidence.json desde una opción de auditoría.',
   EVIDENCE_STALE: 'refresca evidencia antes de continuar con commit/push.',
   EVIDENCE_TIMESTAMP_INVALID: 'regenera evidencia para obtener un timestamp válido.',
@@ -54,7 +55,9 @@ export const buildConsumerPreflightHints = (
   const actionableHintsByCode = resolveActionableHintsByCode(dependencies);
 
   if (hasViolationCode(violations, 'EVIDENCE_MISSING')) {
-    hints.push('Evidence missing: ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.');
+    hints.push(
+      'Evidence missing: ejecuta una auditoría (1/2/3/4 o motor 11–14) para regenerar .ai_evidence.json.'
+    );
     handledCodes.add('EVIDENCE_MISSING');
   }
   if (hasViolationCode(violations, 'EVIDENCE_INVALID')) {