Saltar a contenido

Auditoría de Alineación Documental — Gastro (2026-07)

Estado de contraste entre documentación, contexto agéntico, estándar documental y código real de apps/gastro/.

1. Veredicto

Gastro quedó sustancialmente alineado con el código real y con docs/standars/documentation_standard.md.

La vertical mantiene una única excepción consciente:

  • la topología frontend/{admin-panel,public-menu,marketing-site} sigue en Nivel 3 y está ratificada por ADR

Fuera de esa excepción, la documentación ya no presenta contradicciones estructurales relevantes sobre:

  • estado de módulos
  • integraciones activas
  • autoridad documental
  • guías operativas principales

2. Qué quedó corregido

2.1 Estado de módulos y narrativa de producto

Se eliminó la contradicción sobre M2:

  • M2 Fidelización ya no aparece como “SIGUIENTE”
  • el estado correcto queda documentado como activo vía Foveo

Fuentes reconciliadas:

2.2 Bounded context loyalty

Se corrigió la ambigüedad que sugería que loyalty era un dominio backend nativo plenamente operativo en Gastro.

Estado correcto:

  • la capacidad de fidelización está activa
  • la ejecución operativa vive hoy en Foveo
  • Gastro integra esa capacidad desde admin-panel

Fuentes reconciliadas:

2.3 Autoridad documental

Antes faltaba una jerarquía clara de “qué documento manda para qué pregunta”.

Ahora existe una capa explícita de autoridad:

Con esto queda separado:

  • documento narrativo
  • documento canónico de estado
  • referencias generadas
  • deuda viva

2.4 Tutoriales y how-to críticos

Se corrigieron las dos guías más expuestas al drift:

Ambas ahora apuntan a rutas, payloads y archivos reales del repo.

2.5 Drift explícito en deuda técnica

Se reconciliaron hallazgos que ya no reflejaban el estado real:

  • WS /ws/menu/{slug} documentado correctamente
  • POST /ai-onboarding/preview marcado como protegido por ai.ingest
  • expectativa de realtime bajada al estado real end-to-end

Fuente:

2.6 Referencias generadas y ownership

Cada bloque 03_REFERENCE declara ya su origen y su condición de autoridad.

Fuentes:

3. Qué quedó conforme al estándar

3.1 AGENTS corto y enrutable

apps/gastro/AGENTS.md ya cumple el criterio operativo de documento corto y de routing. La regla local de calidad exige máximo 150 líneas.

3.2 Diátaxis más limpia

La documentación quedó mejor separada por propósito:

  • tutoriales para flujos guiados
  • how-to para tareas concretas
  • reference para artefactos canónicos o generados
  • explanation para estado, decisiones y excepciones

3.3 Menos duplicación peligrosa

La narrativa de estado ya no se reparte arbitrariamente entre:

  • README
  • AGENTS.md
  • .agent/context/project.md
  • tickets de deuda

Ahora el estado real se concentra en:

3.4 Auditoría reproducible

Se agregó una compuerta automática para detectar drift:

Y su procedimiento:

4. Excepciones y deuda real restante

4.1 Excepción aceptada

Se mantiene la excepción de topología Nivel 3 en frontend/. No es incumplimiento accidental; es decisión ratificada.

4.2 Realtime todavía no está cerrado end-to-end

Sigue siendo correcto decir:

  • backend expone WebSocket
  • los frontends públicos no consumen todavía ese canal

Esto ya no es contradicción documental; ahora es deuda técnica explícita en TECH_DEBT.md.

4.3 La calidad futura depende de regenerar referencias

La alineación quedará sostenible solo si se ejecuta de forma rutinaria:

  • generación de referencias backend/frontend
  • reconstrucción de llms-full.txt
  • revisión de drift textual

5. Resultado operativo

Hoy la vertical ya tiene una respuesta clara para estas preguntas:

  • qué documento manda según el tipo de duda
  • qué módulos están activos vs futuros
  • qué integración loyalty está realmente operativa
  • qué rutas y flujos deben usarse en onboarding y theming
  • qué excepción estructural sigue vigente y por qué

Conclusión final:

  • alineación documental: en verde con excepción ratificada
  • deuda restante: localizada y explícita
  • riesgo principal residual: drift futuro si no se corren los quality gates

6. Re-verificación (2026-07-12, tras la auditoría vs SV_Standard_Backend.md)

Re-chequeo puntual pedido por el founder tras las auditorías Atomic Design (frontend, PR #131) y SV_Standard_Backend.md (backend, PRs #132–#134) de esta sesión, contra documentation_standard.md completo (§0–13).

Sigue en verde, confirmado de nuevo: - Índice de ADRs en backend/docs/README.md completo (11/11, ADR-001 a ADR-011). - llms.txt+llms-full.txt presentes en raíz y en apps/gastro/; llms-full.txt se regenera solo en CI tras cada merge a main (confirmado: el bot lo hizo ~15s después de PR #134) — la línea roja #13 (más de 24h sin regenerar) no aplica. - Triada README+AGENTS.md+docs/Diátaxis completa en los 6 niveles de gastro; todos los AGENTS.md ≤150 líneas; 03_REFERENCE sigue 100% auto-generado (backend + los 3 frontends); .github/CODEOWNERS tiene entrada para apps/gastro/.

Hallazgo nuevo, corregido en esta misma pasada (anti-duplicación, §8): - apps/gastro/AGENTS.md ("Gastro no hace hoy") listaba "pedidos/KDS activos en producción" como un solo negativo — correcto para KDS, pero falso para pedidos: Caja (M3.1) y Salón (M3.2.2) llevan semanas activos en producción, reforzados hoy con RLS. current-state.md ya lo tenía bien; AGENTS.md (el documento que un agente nuevo lee primero) contradecía esa fuente. Corregido: se separó el POS/Salón como positivo explícito, KDS quedó solo como negativo. - .agent/context/project.md describía M3.2.2 como si "B" (service_status, comandar, notas de cocina, historial por mesa) siguiera pendiente — desactualizado desde hace varias sub-entregas (tasks_active.md ya documentaba b2 a b15 completos). Corregido: ahora refleja que solo falta C (WebSocket).

Conclusión de esta re-verificación: sigue en verde, con el mismo tipo de drift narrativo de bajo riesgo que motivó la auditoría original (estado de módulos repetido en más de un doc, uno se queda atrás) — no un problema estructural nuevo.