Máquina de Estados Finita (FSM) & Consistência de Change Sets

No ecossistema yzex-tech, o ciclo de vida de desenvolvimento de software (SDLC) é governado por uma Máquina de Estados Finita (FSM) determinística e por um modelo de Consistência Coordenada de Change Sets Multi-Repo.

1. Máquina de Estados Finita do SDLC

A FSM substitui transições informais por contratos de estado estritos:

DRAFT -> READY -> APPROVED -> ISSUES_CREATED -> IMPLEMENTING -> PR_OPEN -> RELEASED -> VERIFIED -> FROZEN_RECEIPT

Cada transição é definida por uma 7-tupla formal: * Source: Estado de origem. * Destination: Estado de destino. * Actor: Agente de IA, desenvolvedor responsável ou esteira automatizada. * Guards: Condições mandatórias que devem ser satisfeitas (ex.: [CI_GREEN], [DOCS_GREEN]). * Action: Operação técnica realizada. * Evidence: Prova observável e durável gerada (commits, logs com exit code 0, hash SHA-256). * Failure: Comportamento determinístico em caso de falha de guardrail (ex.: transição para DEPLOY_FAILED ou ROLLED_BACK).

2. Consistência Coordenada vs. Atomicidade Distribuída

Sistemas de controle de versão baseados em Git distribuído não oferecem transações atômicas nativas entre múltiplos repositórios independentes. Para eliminar o risco de releases parciais incoerentes, adota-se a Consistência Coordenada:

  1. Identificador Global (CS-YYYYMMDD-XXX): Vincula todas as branches, commits e Pull Requests participantes de uma entrega multi-repo.

  2. Ordem Determinística de Merge: Módulos de política e governança são liberados previamente aos serviços dependentes.

  3. Bloqueio por Falha Concorrente: A falha de testes ou compilação de documentação em qualquer um dos repositórios congela o avanço de todo o Change Set.

  4. Procedimento de Compensação: Planos de reversão ou correção para frente (Forward-Fix) são declarados antecipadamente no Change Set.

3. Taxonomia Documental Quadripartite

Para eliminar o apodrecimento da documentação técnica e separar deliberações temporárias de contratos estáveis de engenharia:

Tipo Localização Canônica Ciclo de Vida Função Epistêmica

Plan

yzex-governance/plan/

Transitório; congelado na aprovação formal.

Responde ao POR QUÊ, aos RISCOS e ao DESIGN da mudança.

ADR

patterns/adrs/ ou docs/…​/adrs/

Perene e versionado.

Registra DECISÕES ARQUITETURAIS duradouras cross-system.

Docs

<repo>/docs/modules/…​ (Antora)

Contínua, viva e atômica.

Documenta COMO o sistema funciona hoje (Docs-as-Code).

Receipt

yzex-governance/receipts/

Permanente e imutável pós-deploy.

Prova auditável de O QUE ACONTECEU (evidências práticas de runtime).