Control-plane evolution playbook (foundations first)

Objetivo: evoluir de forma segura do control-plane local para delegação e, só depois, para federação multi-control-plane — sem misturar conceitos no mesmo ciclo.

Distribuição operacional: o núcleo deste playbook também viaja como skill versionada em packages/lab-skills/skills/control-plane-ops/SKILL.md para reduzir drift entre documentação local e comportamento dos agentes.

Radar estratégico relacionado: docs/research/linux-agent-primitives-radar-2026.md (limpeza -> pesquisa -> escalabilidade com gates de promoção local-safe).

Princípios

1. Playbook-first: consolidar contrato operacional antes de ampliar arquitetura.
2. State in parent: estado canônico permanece no control-plane principal (.project/*).
3. Workers are disposable: subagentes/swarm são efêmeros (spawn -> slice -> evidence -> kill).
4. Federation is a phase, not a flag: coordenação federada entra apenas após estabilidade comprovada das fases anteriores.

Três modos (não misturar)

Modo 1 — Single control-plane (agora)

• Escopo: 1 projeto / 1 board canônico.
• Fluxo: execução direta + micro-delegação controlada.
• Gate mínimo: readiness strict (subagent_readiness_status(strict=true)) + budget saudável.
• Critério de saída: 3+ ciclos estáveis com evidência reprodutível e sem recovery manual frequente.

Modo 2 — Delegação descartável (próximo)

• Escopo: subagentes/swarm por fatia.
• Ciclo de vida padrão: spawn -> executar -> retornar evidência -> encerrar.
• Regras:
  • budget cap curto por run;
  • sem memória estratégica no worker;
  • decisão e priorização sempre no parent control-plane.
• Critério de saída: throughput melhora sem aumento de incidentes de contexto/budget.

Modo 3 — Federação de control-planes (futuro)

• Escopo: múltiplas instâncias (projetos distintos) sob coordenação superior.
• Papel do coordenador: rotear, observar, consolidar sinais e governança global.
• Pré-condições:
  • contratos de handoff e evidência padronizados entre instâncias;
  • telemetria mínima comum (status/readiness/budget/health);
  • runbook de contenção para isolar instância degradada sem parar o ecossistema.

Workload matrix — local vs remoto (GitHub Actions/offload protegido)

Objetivo: usar runners remotos como acelerador, sem substituir governança local-first.

Fica local por default

• triagem de task, decisão de prioridade e fechamento canônico no board;
• microfatias de implementação com blast radius pequeno;
• qualquer alteração de escopo protegido sem autorização explícita.

Elegível para runner remoto (canário bounded)

• testes pesados ou longos que saturam host local;
• validações paralelas de baixa ambiguidade (mesmo gate local, mesma métrica);
• jobs de preparo/reporte com artefato auditável (sem auto-promote).

Não elegível para offload automático

• publish/release final;
• mutações de settings/governança sem decisão do operador;
• ações destrutivas/irreversíveis.

Trilha de evidência para offload (board/handoff)

Cada run remota deve registrar, no mínimo:

• task, owner, decision(promote|defer);
• workflow, runId, result, artifacts;
• expectedValue, focalValidationGate, rollbackPlan.

Template prático local:

pnpm run offload:evidence:template -- --task TASK-BUD-134 --decision defer

Steer/Intervenção do Operador (cancel/retry/override)

• cancel: parar run quando custo/qualidade/governança saírem do envelope.
• retry: repetir apenas com motivo curto + gate focal explícito.
• override: exceção auditável e temporária, com rollback já definido.

Sem esse trio de controles, a recomendação padrão é defer.

Release lane (v0.8.0) — draft primeiro, publish gateado

Fluxo end-to-end recomendado:

1. preparar versão (changeset version) e validar alinhamento de versões nos pacotes;
2. rodar pnpm run release:evidence:refresh para atualizar canaries locais, readiness, draft preview e final gate;
3. revisar o artifact .artifacts/release-cut/vX.Y.Z-final-gate.json e os prompts protegidos;
4. criar draft release manual para revisão do operador;
5. publicar somente após gates canônicos + decisão explícita.

Automação mínima existente:

• publish.yml mantém publish gateado por tag semver + smoke/test/verify/audits;
• release-draft.yml prepara draft release manual com artefato de notas;
• pnpm run release:readiness -- --target X.Y.Z gera checklist local canônico para qualquer target;
• pnpm run release:readiness:json -- --target X.Y.Z gera o mesmo contrato em JSON para agentes;
• pnpm run release:readiness:strict -- --target X.Y.Z aplica o mesmo contrato como gate local não-verde;
• pnpm run release:readiness:strict:json -- --target X.Y.Z aplica o gate e preserva o artefato estruturado;
• pnpm run release:readiness:v0.8.0 gera checklist local canônico em .artifacts/release-readiness/.
• pnpm run release:readiness:v0.8.0:json gera o mesmo estado em JSON para agentes e automação local, incluindo operatorDecisions.
• pnpm run release:evidence:refresh -- --target X.Y.Z atualiza a cadeia segura local: agent-run:driver-canaries, readiness, draft preview, cut preview auditado, artifact audit e final gate.
• pnpm run release:evidence:refresh:json -- --target X.Y.Z emite o mesmo packet em JSON legível; o resultado esperado antes de revisão do operador é mode=release-evidence-refresh, decision=pass, finalGateDecision=pass e protectedActionsAllowed=false.
• pnpm run release:evidence:status -- --target X.Y.Z lê a evidência já materializada e retorna um resumo release-evidence-status sem rodar canários, sem escrever artefatos e sem ações protegidas.
• pnpm run release:final:gate -- --target X.Y.Z recompõe em memória cut preview + artifact audit + cut auditado sem tag, push, workflow dispatch ou publish.
• pnpm run release:artifact:audit -- --target X.Y.Z audita artifacts já gerados quando for necessário inspecionar a cadeia manualmente.

Interpretação do readiness report:

• Release Blockers separa gate técnico, decisão de operador e estado do board;
• Operator Decisions lista as decisões do operador restantes antes do release;
• no JSON, mode=release-readiness-report e schemaVersion=1 identificam o contrato estruturado;
• no JSON, markdown acompanha o mesmo relatório legível para operador, então agentes não precisam escolher entre contrato estruturado e contexto legível;
• no JSON, generatedAt e decision identificam o snapshot e a decisão (ready ou not-ready) sem parsear Markdown;
• no JSON, versions, versionsAligned, targetVersionReady, workflows, gates, worktree, agentRunDrivers, packageSmoke e userSurface expõem os gates principais sem parsear checklist[*].evidence;
• no JSON, gates.worktreeClean e worktree.statusLines bloqueiam readiness quando há mudanças rastreadas locais; arquivos untracked de evidência local não bloqueiam por si só;
• no JSON, agentRunDrivers.canaryScriptName e missingCanaryScriptMarkers expõem se o comando local agregado agent-run:driver-canaries está registrado para materializar evidência;
• no JSON, agentRunDrivers.canarySuiteEvidence aponta .artifacts/agent-run-driver/suite.json; para readiness de release, essa suíte agregada precisa existir, retornar decision=pass e, quando HEAD Git estiver disponível, carregar gitHead igual ao head do relatório;
• no JSON, agentRunDrivers.lastCanaryEvidence pode apontar .artifacts/agent-run-driver/latest.json como evidência local advisory; ausência desse arquivo não bloqueia release por si só;
• no JSON, agentRunDrivers.lastMutationCanaryEvidence pode apontar .artifacts/agent-run-driver/latest-mutation.json como evidência local advisory de file_contract=mutation;
• no JSON, userSurface resume a auditoria pi-stack:user-surface e bloqueia readiness se houver scripts raiz lab-only ou promotion-candidate sem assimilação explícita;
• pnpm run agent-run:driver-canary produz essa evidência local com um canário bounded de node --version, sem provider real, sem fan-in e sem colônia;
• no JSON, checklist[*].kind classifica cada gate como technical-gate, operator-decision ou board-state;
• no JSON, releaseBlockers expõe os mesmos bloqueios do Markdown com id, kind e evidence;
• no JSON, operatorDecisions[*] inclui payload acionável por decisão, como allowedActions, versões atuais e candidateTaskIds;
• no JSON, operatorDecisions[*].releaseVersionDecisionPacket aparece quando target-version-ready está falso; ele inclui currentVersions, recommendedAction e requiredApprovalPrompt sem editar manifestos, tags ou publish;
• no JSON, operatorDecisions[*].boardReleaseDispositionPacket aparece quando o board tem candidatos com evidência de release; ele lista dispositionRows[*].recommendedAction, dispositionRows[*].approvalPrompt e requiredApprovalPrompt sem editar .project/tasks.json nem autorizar automação;
• no JSON, nextActions[*].boardReleaseDispositionPacket replica esse packet quando ele for o próximo passo, permitindo consumo direto de nextActions sem inferência adicional;
• no JSON, nextActions[*].releaseDraftReviewPacket aparece quando todos os gates estão verdes; ele exige requiredApprovalPrompt e mantém tagAllowed, publishAllowed, workflowDispatchAllowed e processStartAllowed falsos;
• no JSON, operatorDecisions[*].requiresOperatorDecision=true e automationAllowed=false deixam claro que allowedActions são opções para operador, não dispatch automático;
• no JSON, nextActionCode e nextActions indicam o próximo passo seguro sem autorizar publish automático;
• no JSON, automationPermissions mantém tagAllowed, publishAllowed, workflowDispatchAllowed e processStartAllowed falsos; readiness report é sempre report-only;
• no final gate, requiredApprovalPrompts lista as aprovações protegidas (tag create, tag push, prepare-draft-release, publish-release) sem executá-las;
• no refresh, protectedActionsAllowed=false confirma que o comando atualiza evidência local e não inicia release real;
• Board Evidence Candidates lista tarefas ainda abertas que já têm evidência local-safe para decisão;
• no JSON, board.openP0Rows, board.inProgressRows e board.blockedRows expõem o estado do board sem exigir parse de linhas Markdown;
• no JSON, board.evidenceCandidateRows expõe os mesmos candidatos em forma estruturada para agentes;
• releaseDecisionReady: yes significa que o board está pronto para decisão explícita, não que o release está aprovado.

Checklist de readiness v0.8.0 (board/handoff):

• versões de pacotes alinhadas;
• CI/publish/release-draft prontos e auditáveis;
• candidatos de evidência do board decididos como park-for-target-release ou require-work;
• decisão explícita do operador de draft -> publish;
• rollback documentado para falha pós-corte.

Inspirado por tuts-agentic-ai-examples

Referência: https://github.com/nilayparikh/tuts-agentic-ai-examples

Mapeamento conceitual (adaptado ao ecossistema pi/refarm):

• Single agent / sequential / parallel / coordinator / agent-as-tool / loop-critique (trilha agents/) -> matriz de padrões de delegação progressiva.
• A2A progressivo e capstone multiagente (trilha a2a/) -> base para contrato entre instâncias e interoperabilidade de runtime.

Adaptação local obrigatória:

• manter board-first (.project/*) como fonte canônica;
• preservar no-auto-close para itens estratégicos;
• promoção por verificação (verification) antes de completed.

Espelho externo de issues/status

Mapeamento canônico:

• .project/tasks[].id é o identificador operacional; issue externa entra como referência em nota/evidência.
• description/título externo são resumo espelhado, não fonte final de verdade.
• labels externas só alteram priority/milestone quando houver mapping explícito registrado.
• status local só muda para completed com verification local passada; fechamento externo não auto-fecha task estratégica.

Direção e conflito:

• default: board-first (.project -> GitHub/Gitea) para mirrors públicos;
• import externo só cria proposta/nota quando houver divergência;
• conflito de status/label/evidência vira nota auditável e exige política/operador, sem overwrite silencioso;
• operações remotas mutantes (gh issue close/edit, labels, milestones) exigem intenção explícita.

Idempotência mínima:

• registrar URL/número externo uma vez por task;
• reaplicar sync não deve duplicar notas ou mudar status sem nova evidência;
• cada sync deve declarar direção, entidade externa, task alvo e campos promovidos/ignorados.

Anti-patterns (evitar)

• transformar subagente em “memória longa” do sistema;
• acoplar decisão estratégica ao worker;
• abrir federação antes de estabilizar operação local;
• compensar arquitetura frágil com compactação frequente.

Checklist GO/NO-GO — transição Modo 1 -> Modo 2

GO (todos obrigatórios)

• subagent_readiness_status(strict=true) retorna ready=true por pelo menos 2 checks consecutivos.
• Últimas runs controladas não apresentam BUDGET_EXCEEDED no recorte operacional.
• Board canônico está íntegro (project-validate clean) e handoff atualizado.
• Delegações curtas já demonstraram retorno auditável (evidência + status de task sem auto-close indevido).

NO-GO (qualquer item bloqueia)

• readiness strict oscilando (ready=false recorrente) por causas não diagnosticadas.
• falha de governança de budget (streak de bloqueio, retries exaustos sem contenção).
• dependência de memória de subagente para decisão estratégica.
• ausência de evidência canônica no parent control-plane.

Envelope mínimo de telemetria — Modo 3 (federação)

Cada control-plane federado deve expor, no mínimo:

• instanceId: identidade estável da instância (workspace/projeto).
• status: running|paused|degraded.
• readiness: resultado gate strict (ready, checks críticos, timestamp).
• budget: estado resumido por provider/account (ok|warn|block).
• lease: owner + heartbeat + expiração.
• workload: fila pendente e task ativa (se houver).
• lastHandoffAtIso: timestamp da última atualização canônica.

Contrato de operação do coordenador federado:

• nunca decidir por contexto implícito de worker;
• sempre agir com base em telemetria explícita + evidência do board local;
• isolar instância degradada sem interromper as saudáveis.

Rollout / rollback por modo

Modo 1 (single control-plane)

Rollout:

1. validar saúde: context_watch_status + project-validate;
2. confirmar gate strict: subagent_readiness_status(strict=true);
3. executar slices locais com board/handoff atualizados.

Rollback (voltar para estabilidade local):

• se houver oscilação de readiness/budget, pausar delegação e voltar para execução direta até 2 ciclos limpos.

Operação noturna local-safe (batch 3–5 fatias, hard-intent)

Contrato operacional para rodar sem check-in entre tasks elegíveis:

1. iniciar com autonomy_lane_next_task e autonomy_lane_auto_advance_snapshot;
2. executar uma fatia curta por vez (commit + checkpoint);
3. permitir auto-advance apenas quando snapshot decision=eligible;
4. manter parada imediata quando snapshot decision=blocked.

Stop conditions mínimos (formato curto):

• stop: protected;
• stop: risk;
• stop: reload-required;
• stop: validation-failed-or-unknown;
• stop: no-eligible-local-safe-successor.

Rollback padrão AFK:

• ação: pausar auto-advance, manter foco explícito e voltar para uma fatia manual bounded;
• evidência: registrar blocker no board + context_watch_checkpoint;
• saída: retomar auto-advance só após blocker limpo e smoke focal verde.

Modo 2 (delegação descartável)

Gate de entrada — simple-delegate rehearsal bounded:

1. simple_delegate_rehearsal_packet.decision == ready;
2. foco local-safe já estável (batch 3–5 concluído com checkpoint/commit por fatia);
3. sem blockers hard-intent (protected, risk, reload-required, validation-failed-or-unknown);
4. escopo protegido continua opt-in do operador (nenhum auto-dispatch).

Canário protegido de capacidade externa (GitHub Actions/offload) — pré-condições:

1. declarar valor esperado do canário (throughput/custo/tempo) com métrica observável;
2. declarar validação focal obrigatória antes/depois (mesmo gate local para comparação);
3. declarar rollback explícito e não-destrutivo (git revert <commit> + retorno imediato ao caminho local);
4. registrar envelope mínimo no board/handoff: task, maxCost, owner, evidence, decision=promote|defer;
5. manter dispatch=no até decisão explícita do operador de promote.

Rollout canário:

1. escolher 1 task curta com critérios claros;
2. executar rehearsal report-first (sem dispatch automático) e só então avaliar execução delegada bounded;
3. exigir evidência no parent antes de nova delegação;
4. encerrar worker após entrega (não manter sessão longa do worker).

Rollback:

• trigger: FAILED recorrente, BUDGET_EXCEEDED, blocked-rate alto no telemetry, ou ausência de evidência canônica;
• ação: descer para Modo 1 por 1 janela operacional (sem novas delegações) e corrigir causa raiz.

Runbook curto — rehearsal real (1 task):

1. start: usar simple_delegate_rehearsal_start_packet; só avançar quando decision=ready-for-operator-decision e houver go explícito do operador;
2. monitor: manter execução bounded e parar no primeiro stop: protected|risk|reload-required|validation-failed-or-unknown;
3. abort: em blocker, encerrar rehearsal no mesmo slice, sem promover próxima task automaticamente;
4. rollback: aplicar rollback não-destrutivo declarado, registrar evidência no board e checkpoint curto;
5. postflight: registrar decisão go/no-go para próxima fatia antes de qualquer novo start.

Modo 3 (federação)

Rollout canário:

1. federar só 1 instância filha inicialmente;
2. validar envelope mínimo (status/readiness/budget/lease/workload/handoff);
3. testar isolamento: simular instância degradada sem afetar as demais.

Rollback:

• trigger: perda de telemetria mínima, lease inconsistente, ou decisões sem evidência local;
• ação: remover instância da federação, manter operação local autônoma, reintroduzir apenas após requalificação.

Sinais esperados por estágio

• Modo 1 saudável:
  • subagent_readiness_status(strict=true).ready == true
  • context_watch_status.level in {ok,warn-controlado}
  • project-validate.status == clean
• Modo 2 saudável:
  • presença de COMPLETE nas runs controladas;
  • ausência de BUDGET_EXCEEDED no recorte operacional;
  • evidência registrada em verification para cada delegação relevante.
• Modo 3 saudável:
  • telemetria mínima disponível para todas as instâncias ativas;
  • coordenador sem decisões “cegas” (sempre com status/readiness/budget/lease);
  • isolamento comprovado de instância degradada sem efeito cascata.