Como Gerenciar Change Sets Coordenados & Recibos de Execução

Este guia orienta o engenheiro e o agente de IA na condução operacional de alterações multi-repo coordenadas e na formalização de provas auditáveis de execução.

1. Conduzindo um Change Set Coordenado

Passo 1: Aprovação Formal da Baseline

Após a redação do Plano de Implementação sob yzex-governance/plan/<contexto>/ e emissão do parecer técnico favorável: 1. Calcule o hash criptográfico SHA-256 da baseline do plano. 2. Obtenha o sign-off do desenvolvedor via modal interativo (ask_question). 3. Atualize o frontmatter do plano para status: APPROVED com o campo baseline_hash.

Passo 2: Inicialização do Change Set

Gere um identificador único de Change Set:

change_set:
  id: "CS-YYYYMMDD-001"
  plan_reference:
    path: "yzex-governance/plan/yzex/..."
    baseline_hash: "sha256:..."
  repositories:
    - name: "yzex-governance"
      target_branch: "main"
    - name: "yzex-docs"
      target_branch: "main"

Passo 3: Criação de Issues e Branches Padronizadas

Para cada repositório afetado: 1. Crie a issue via gh issue create --body-file buffer.md contendo a referência ao CS-YYYYMMDD-001. 2. Crie a branch local a partir da main sincronizada:

+

git checkout -b feature/<issue-id>-<slug>

Passo 4: Desenvolvimento Atômico e Quality Gates

Desenvolva aplicando a Tríade Local Atômica (Código, Testes automatizados e Documentação .adoc). Submeta os Pull Requests associando ao Change Set.

2. Formalizando o Execution Receipt

Após a aprovação de todos os Quality Gates e merge na branch main (status: RELEASED):

Passo 1: Validação Empírica em Tempo de Execução

Execute testes de fumaça reais no terminal via Infisical:

infisical run --env=dev -- <comando_de_smoke_test>

Passo 2: Emissão do Recibo Auditável

Crie o arquivo sob yzex-governance/receipts/<timestamp>_<slug>.receipt.md:

receipt_version: "2.0.0"
execution_id: "REC-YYYYMMDD-001"
change_set_id: "CS-YYYYMMDD-001"
plan_metadata:
  plan_id: "<timestamp>_<slug>"
  baseline_hash: "sha256:..."
audit_trail:
  approver: "ErikOliveiraDev"
  approval_timestamp_utc: "2026-09-11T12:30:00Z"
  target_environment: "dev"
execution_evidence:
  issues:
    - id: "#123"
      repo: "yzex-governance"
  pull_requests:
    - id: "#45"
      repo: "yzex-governance"
      commit_sha: "abc1234"
  runtime_attestation:
    command: "node scripts/validate-ecosystem.cjs"
    exit_code: 0
    executed_at_utc: "2026-09-11T12:45:00Z"
deviations_and_reconciliation:
  has_deviations: false
  notes: "Entrega em estrita conformidade com a baseline deliberativa."

Passo 3: Congelamento

Comite o arquivo de recibo no repositório yzex-governance. Uma vez persistido, ele torna-se imutável (FROZEN_RECEIPT).