fix(tpv-dev-in-prod): tPV production is running next dev (HMR + React DevTools visible)

work/artifacts/TPV-DEV-IN-PROD/documenter.md

@@ -0,0 +1,87 @@
+# TPV-DEV-IN-PROD — Documenter notes
+
+> Documenter: document · Estado: ready for close
+
+## Cambio de contrato con el operador
+
+El script `project/scripts/monolith.sh` añade un **smoke test post-arranque**
+que se ejecuta exclusivamente cuando `MODE == "prod"`. Si detecta que alguno
+de los 4 servicios Next.js (admin, tpv, frontend, storefront) está sirviendo
+`next dev` en lugar de `next start`, **abort el despliegue ruidosamente** y
+deja al host en estado limpio.
+
+Esto es un cambio de contrato porque:
+
+1. **Antes:** `monolith.sh prod start` siempre terminaba con `print_urls`
+   aunque un dev server estuviera ocupando el puerto.
+2. **Después:** `monolith.sh prod start` puede abortar con exit code 1 si
+   detecta dev mode. El operador verá un mensaje claro apuntando a
+   `docs/HOWTO-monolith.md` §3.1 y deberá seguir el runbook de recuperación.
+
+## Quién se ve afectado
+
+- **Operador del host público** (TPV-MV, Admin-MV, Storefront-MV): nuevo modo
+  de fallo al desplegar. Mitigado por el runbook §3.1.
+- **Operador de dev local** (`monolith.sh dev start`): **sin cambios**. El
+  smoke test solo se ejecuta en prod.
+- **Usuarios finales** del TPV: sin cambios visibles. La corrección resuelve
+  un bug suyo (HMR en consola, dev internals expuestos, PWA rota por CORS).
+
+## Dónde está documentado
+
+| Documento | Cambio |
+|---|---|
+| `docs/HOWTO-monolith.md` §3 | Línea nueva explicando el smoke test post-arranque. |
+| `docs/HOWTO-monolith.md` §3.1 | **Nuevo**: errores comunes, señales de dev mode, runbook de 6 pasos. |
+| `docs/HOWTO-monolith.md` §6 | Nuevo bloque "Comprobaciones adicionales anti-dev" en el checklist post-deploy. |
+| `docs/pos/POS_OPERATIONS.md` §1.3 | Bloque de advertencia inline apuntando a §3.1 de HOWTO-monolith. |
+
+Los usuarios del script **no necesitan leer este documenter.md** — toda la
+información operacional vive en `docs/HOWTO-monolith.md` y
+`docs/pos/POS_OPERATIONS.md`. Este documento sirve de índice y registro del
+contrato.
+
+## API / endpoint contract
+
+Sin cambios. No se ha tocado ningún endpoint HTTP, ninguna ruta del TPV, ningún
+módulo backend, ni ningún schema de base de datos. El fix es puramente
+operacional (deploy hardening).
+
+## User-facing behavior
+
+Sin cambios. El comportamiento observable para usuarios finales es idéntico:
+la app TPV sigue cargando, los productos siguen listándose, los pagos siguen
+procesándose. Lo único que desaparece (o más bien: deja de aparecer) es el
+ruido de HMR + React DevTools en la consola del navegador.
+
+## Notas de release (sugeridas para próximo CHANGELOG / commit body)
+
+```
+fix(monolith): add HMR-free smoke test to prod start (TPV-DEV-IN-PROD)
+
+Adds post-arranque smoke check that fails loudly if any of the four
+Next.js services (admin, tpv, frontend, storefront) is serving next dev
+instead of next start. Detection covers three independent dimensions:
+HTML markers, /_next/hmr endpoint, and (Turbopack) banner in log.
+
+Hardens docs/HOWTO-monolith.md §3.1 (signals + 6-step runbook) and
+docs/pos/POS_OPERATIONS.md §1.3 (inline warning).
+
+Verified with two controlled mocks:
+  - dev server mock → smoke returns exit=1 with 2 FAILs
+  - prod server mock → smoke returns exit=0 with OK
+```
+
+## Cross-references
+
+- architect.md §2 — diseño de las 3 capas (smoke + docs + runbook).
+- architect.md §7 — tabla de riesgos y mitigaciones.
+- implementer.md §5 — evidencia de verificación.
+- reviewer.json checks — 10/10 PASS.
+- security.json checks — 10/10 PASS.
+- qa.json — 8/8 AC + 4/4 integration + 4/4 regression PASS.
+
+## Próximo stage
+
+→ **close (leader)**: ejecutar `scripts/close_feature.py TPV-DEV-IN-PROD`
+para promover a `done`, commit, push.