Saltar a contenido

FSM de Sincronizacion de Ramas, Hosts y Entornos

Objetivo

Dar a Kabehz, L0KY y AJCG131281 una FSM unica para sincronizar rama compartida, host local y entorno operativo usando atq como entrada corta.

Comando canónico

La entrada recomendada ya no debe ser recordar varios pasos manuales.

Debe ser:

bash bash scripts/atq collab sync \ --role reviewer \ --collaborator-id <id> \ --oauth-bundle-file .secrets/governance/oauth/local-collaborators/<id>/bundle.env \ --team devsecops

Si el colaborador necesita nodo completo:

bash bash scripts/atq collab sync \ --role full-node \ --collaborator-id <id> \ --oauth-bundle-file .secrets/governance/oauth/local-collaborators/<id>/bundle.env \ --team devsecops

Qué sincroniza esta FSM

  1. rama fuente común y rama edge personal
  2. contrato de host local (staging.atlantyqa.local u otro)
  3. bundle OAuth gobernado del colaborador
  4. runtime local-first y bootstrap canónico
  5. validación mínima del nodo antes de tareas reales

FSM operativa

graph TD
    S0[S0_ENTRY<br/>definir actor y rol] --> S1[S1_CLEAN_TREE<br/>validar repo limpio]
    S1 --> S2[S2_BRANCH_SYNC<br/>fetch checkout pull y edge branch]
    S2 --> S3[S3_HOST_ENV_BOOTSTRAP<br/>hosts bundle runtime]
    S3 --> S4[S4_NODE_DOCTOR<br/>validar contratos del nodo]
    S4 --> S5[S5_PR_CONTEXT<br/>leer issue PR y objetivo]
    S5 --> S6[S6_READY_TO_WORK<br/>nodo sincronizado]
    S1 --> F1[F1_DIRTY_TREE<br/>hay cambios locales]
    S2 --> F2[F2_BRANCH_BLOCKED<br/>fallo de fetch checkout pull]
    S3 --> F3[F3_HOST_ENV_BLOCKED<br/>hosts bundle runtime fallan]
    S4 --> F4[F4_DOCTOR_FAIL<br/>guards locales fallan]
    S5 --> F5[F5_CONTEXT_GAP<br/>PR o issue no entendible]
    F1 --> S1
    F2 --> S2
    F3 --> S3
    F4 --> S4
    F5 --> S5

    style S0 fill:#182232,stroke:#182232,stroke-width:2px,color:#ffffff
    style S6 fill:#37a880,stroke:#2d7f63,stroke-width:2px,color:#ffffff
    style F1 fill:#ffffff,stroke:#c94b4b,stroke-width:2px,color:#182232
    style F2 fill:#ffffff,stroke:#c94b4b,stroke-width:2px,color:#182232
    style F3 fill:#ffffff,stroke:#c94b4b,stroke-width:2px,color:#182232
    style F4 fill:#ffffff,stroke:#c94b4b,stroke-width:2px,color:#182232
    style F5 fill:#ffffff,stroke:#c94b4b,stroke-width:2px,color:#182232

Tabla de estados

Estado Qué valida Comando o evidencia Resultado esperado
S0_ENTRY actor, rol y bundle correctos issue de onboarding + bundle individual se sabe quién sincroniza y para qué
S1_CLEAN_TREE repo sin drift local git status --short árbol limpio para sync atómica
S2_BRANCH_SYNC rama fuente y edge branch bash scripts/atq collab sync ... source branch actualizada y edge branch activa
S3_HOST_ENV_BOOTSTRAP host local, runtime y OAuth bootstrap canónico host y entorno alineados con el contrato
S4_NODE_DOCTOR guards de workflows y runtime bash scripts/atq collab doctor --collaborator-id <id> PASS o bloqueo explícito
S5_PR_CONTEXT comprensión de issue/PR PR activa + control plane el colaborador sabe qué toca después
S6_READY_TO_WORK sincronización real completada evidencia en outputs/ + PR/bitácora el nodo ya puede trabajar

Estados de bloqueo

Estado Significado Acción correcta
F1_DIRTY_TREE el repo tiene cambios sin cerrar commit o stash antes de sincronizar
F2_BRANCH_BLOCKED fetch, checkout o pull fallan corregir rama remota o conflicto y reintentar
F3_HOST_ENV_BLOCKED host, bundle o runtime fallan revisar bundle, /etc/hosts, runtime y preflight
F4_DOCTOR_FAIL los guards locales fallan abrir el log del doctor y corregir antes de seguir
F5_CONTEXT_GAP el colaborador no entiende la PR o la tarea resumir objetivo, evidencia y siguiente paso

Secuencia recomendada por actor

Kabehz

bash bash scripts/atq collab sync \ --role reviewer \ --collaborator-id kabehz \ --oauth-bundle-file .secrets/governance/oauth/local-collaborators/kabehz/bundle.env \ --team devsecops

L0KY

bash bash scripts/atq collab sync \ --role reviewer \ --collaborator-id l0ky \ --oauth-bundle-file .secrets/governance/oauth/local-collaborators/l0ky/bundle.env \ --team devsecops

AJCG131281

bash bash scripts/atq collab sync \ --role reviewer \ --collaborator-id ajcg131281 \ --oauth-bundle-file .secrets/governance/oauth/local-collaborators/ajcg131281/bundle.env \ --team devsecops

Qué deja como evidencia

  1. rama sincronizada contra la fuente común
  2. host local y bundle aplicados bajo wrapper canónico
  3. outputs/collaborators/<id>/doctor-*/summary.md si se ejecuta doctor
  4. siguiente acción clara en issue, PR o bitácora

Regla de cierre

  • si el nodo no llega a S4_NODE_DOCTOR, no se considera listo
  • si el nodo no entiende la PR tras S5_PR_CONTEXT, no se considera sincronizado de verdad
  • mejor bloqueado con causa que sincronizado solo de nombre