Flujo Canónico Triada → Staging → Main¶

Objetivo

Definir un único contrato operativo para que Kabehz, L0KY y AJCG131281 contribuyan de forma trazable, humanizable y compliant mediante bot-aidlc-atlantyqa, priorizando estabilidad de staging antes de cualquier promoción a main.

Orden canónico (único flujo)¶

Gobierno triada primero
Cierre formal de PR activa (ejemplo: PR148) con evidencia enlazada.
Confirmación de triada en bitácora/contexto/policies.
Si la PR activa es la mega PR canónica, usar la plantilla de bloque: docs/internal/triad-mega-pr-block-template.md
Sin esta confirmación, no se inicia promoción técnica.
Staging técnico después
Ejecutar micro-olas por lotes (ejemplo #159):
- Lote 1: Longhorn
- Lote 2: Observability
Aplicar gates no disruptivos en atlantyqa-staging.
Cerrar cada lote con evidencia + rollback explícito.
Promoción de ramas por prioridad
Rama base de integración staging:
- collab/kabehz/env-ops/hostproxmox-mainline-thin-20260319
Ramas por lote:
- collab/kabehz/sre/issue-159-longhorn-<fecha>
- collab/kabehz/sre/issue-159-observability-<fecha>
Merge por lote hacia rama base de integración.
Solo tras aprobación triada explícita: PR de integración hacia main.

Contrato técnico: Dual-Lane in One Repo¶

text atlantyqa-universe/ infra/ # inmutable/gobernado runtime/ # mutable/controlado

infra/: solo estado deseado declarativo y cambios gobernados.
runtime/: estado operativo controlado y automatizaciones de ejecución.
CI bloquea artefactos runtime dentro de infra/.

Gobierno bidireccional multi-repo/proyectos¶

atlantyqa-universe sigue siendo control-plane único y source-of-truth, pero gobierna bidireccionalmente:

repositorios/proyectos adoptados (incluidos forks OSS como openNotebook)
repositorios/proyectos creados por la triada

Modelo:

universe -> satélites: políticas, contratos, taxonomía, gates.
satélites -> universe: evidencia de ejecución, estado, riesgos y decisiones humanas.

Arquitectura técnica y flujos colaborativos (visual)¶

1) Vista técnica (repos, runtime y evidencia)¶

graph TD
    A[Repo Infra / Integración staging] --> B[Runbook reconcile + guards]
    B --> C[VMHOST / MicroK8s]
    C --> D[Namespace atlantyqa-staging]
    C --> E[Longhorn + Observability]
    D --> F[Portal/OAuth/GitHub App]
    B --> G[Artefactos y evidencia]
    G --> H[Issue + PR + Bitácora]
    H --> I[Decisión triada]
    I --> J[Promoción a main]

1.1) Segregación por capa OSI (para lectura cognitiva)¶

Capa OSI	Superficie ATLANTYQA	Qué validar
L7 Aplicación	Ingress, OAuth2, Portal, GitHub App, Tech-Radar	rutas, auth, UX/UI, códigos HTTP
L6 Presentación	TLS/cert-manager/Let's Encrypt	validez de cert, issuer, renovación
L5 Sesión	sesiones OAuth2/proxy y callbacks	continuidad de login y claims
L4 Transporte	TCP 80/443, timeouts, probes	reachability, latencia, resets
L3 Red	DNS/NAT/route entre internet-router-VM	resolución FQDN e IP destino
L2 Enlace	bridge virtual, NIC VM, CNI/Calico	conectividad nodo-cluster estable
L1 Física	host baremetal, puertos físicos, energía	disponibilidad base de infraestructura

Regla: los lotes de remediación en #159 inician en L7/L6 y bajan de capa solo si la evidencia obliga.

2) Flujo M2M (Machine-to-Machine)¶

sequenceDiagram
    participant CI as CI/Guards
    participant RB as Runbook
    participant VM as VMHOST
    participant K8s as MicroK8s
    CI->>RB: validar contratos + templates + policies
    RB->>VM: sync rama + env + runtime stateless
    VM->>K8s: kubectl apply/validate
    K8s-->>RB: estado + eventos + certificados
    RB-->>CI: reportes/run-summary/evidencia

3) Flujo H2M y H2H (Human-in-the-loop)¶

graph LR
    K[Kabehz] --> CP[Control Plane]
    L[L0KY] --> CP
    A[AJCG131281] --> CP
    CP --> H2M[H2M: aprobación HILT + comandos guiados]
    H2M --> EV[Evidencia técnica]
    EV --> H2H[H2H: decisión triada]
    H2H --> S[Staging aprobado]
    S --> M[PR a main con decisión humana explícita]

Gates obligatorios de no impacto¶

microk8s kubectl -n atlantyqa-staging get deploy,svc,ing saludable.
Probes portal sin degradación (http=308, https=302 o mejor).
run-summary sin nuevos errores bloqueantes.

Matriz CI/CD por entorno (single-repo)¶

Entorno	CI	CD	Gate humano
`local-*` colaborador	validaciones locales + evidencia	no aplica promoción	obligatorio para decisiones
`staging` (`root@asesor` + VM)	checks PR + guards	reconcile manual-gated	HILT obligatorio
`preprod`	checks + contrato release	promoción desde tag/commit firmado	aprobación explícita + ventana
`prod`	checks + contrato release reforzado	promoción desde tag/commit firmado	aprobación explícita + ventana

Comando canónico por entorno:

bash bash scripts/atq-env-promote.sh <local-validate|staging-validate|staging-apply|preprod-promote|prod-promote> ...

Checklist rápido de decisión humana¶

[ ] Evidencia operacional enlazada (run_id, logs, reportes).
[ ] Riesgo residual declarado (bajo/medio/alto).
[ ] Siguiente paso único definido.
[ ] Estado final por rama: mergeable|needs-small-fix|blocked.

Contrato de enforcement¶

Este documento debe estar referenciado en:

PR template principal
PR template OPS/runtime
Issue template de incidente OPS/runtime
Issue template router
Runbook de reconcile

Además, CI debe verificar estas referencias con un guard automático.

Baseline de branch protection¶

Contrato declarativo: .github/contracts/branch-protection-single-repo-multi-env.json
Auditoría operativa: bash scripts/github/audit_branch_protection_rulesets.sh [--strict]