@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/README-ENG.md

@@ -8,7 +8,7 @@ English | [Português](README.md)
 
 ZAIP-AIOS is an operating system for autonomous work performed by AI agents. It coordinates 23 specialized agents, organized into six squads, within Codex.
 
-Agents plan, execute, review, test, and validate work under the orchestrator's coordination. Authorized execution proceeds until it meets the defined criteria or records a blocker, failure, or budget limit. External dependencies and decisions outside the granted authority still require human intervention; autonomy does not mean indefinite execution or a guarantee of success.
+Agents plan, execute, review, test, and validate work under the orchestrator's coordination. Authorized execution continues until acceptance or an evidence- and budget-based blocked/failed outcome. Persistent permits indefinite execution by explicit choice; other presets have per-Task quotas. No preset guarantees success or expands authority for external actions.
 
 The approach seeks to reduce intervention, unnecessary context, and rework. The 34% and 62% figures below refer respectively to average cost per task and per hour in the illustrated historical series; they do not directly measure token reduction or guarantee savings in a new delivery.
 
@@ -49,22 +49,34 @@ The Dashboard uses a local, disposable, rebuildable database only as a query and
 
 ### How to read this documentation
 
+Both READMEs are maintained in Portuguese and English. Dashboard Help loads
+the canonical English README; guides without translations show the current
+Portuguese source with a language notice, not stale parallel summaries.
+
 This README and the [handbook](zaip-aios/INDEX.md) describe this repository's source code. Effective configuration, host support, the installed package, and a qualified candidate are distinct dimensions. `@latest` points to the published version, which may not include local changes. Dashboard images illustrate prior states; they are not visual proof of the current candidate.
 
 Documentation changes do not approve a release. Consult the [qualification-limits record](https://github.com/zaip-ai/zaip-aios/blob/main/docs/PRODUCTION-COMMERCIAL-READINESS.md#limites-conhecidos-da-qualificação) before promoting code; local tests, parity, CI, and production validation must be proven separately.
 
+For v3 delivery, the complete suite runs in signed local preparation (`full-v2`). GitHub verifies the exact package, installation and publication without repeating source tests on every push. Activation requires full local qualification and enrolled trust. One automatic installation smoke precedes npm publication; source checks and the remote matrix are manual, with no private-draft pilot. See the [quality and release guide](zaip-aios/guides/26-qualidade-e-release.md). Historical telemetry gaps remain explicit, without invented values or waived tests for new data.
+
 ## One-command installation
 
 With Node.js 22.16.0 or later and npm, run installation at the root of the project that will receive ZAIP-AIOS. In a fresh installation, `init` uses the full (`full`) profile: it installs missing stack dependencies and prepares Terraform. Every profile checks distributed runtimes and prepares and validates local SQLite without a separate driver. Existing package versions are preserved, with a notice showing the installed and ZAIP-AIOS-configured versions:
 
 ```bash
-npx @zaip-ai/cli@latest init
+npx --yes @zaip-ai/cli@latest init --project-only
+node .agents/runtime/bin/zaip.mjs doctor --json
 ```
 
-You can also automatically accept the CLI's initial download by `npx`:
+These are the two steps for the first verified result: `init` installs the
+framework in the selected project without changing global Codex configuration,
+and `doctor --json` confirms the installed layout, checksums, and adapters. The
+result is ready only when the JSON returns `"valid": true`.
+
+Review the plan before writing to the project:
 
 ```bash
-npx --yes @zaip-ai/cli@latest init
+npx --yes @zaip-ai/cli@latest init --project-only --dry-run
 ```
 
 Both commands use the profile saved in the project, or `full` if no choice exists. `--yes` before the package name accepts only the CLI's initial `npx` download; it does not force replacement of existing dependencies, files, or versions. It can be combined with any profile, for example `npx --yes @zaip-ai/cli@latest init --profile lite`. `init --yes`, after the package name, confirms replacement requested by `--force`. Use `--force --yes` only after reviewing the dry run; the installer creates a backup before replacement.
@@ -218,6 +230,42 @@ Platform configuration shows ZAIP-AIOS activation state and a summary of agents,
 
 <img src="https://raw.githubusercontent.com/zaip-ai/zaip-aios/main/.agents/config/src/dashboard_pt_configuracao_plataforma.png" alt="ZAIP-AIOS Dashboard, platform configuration" width="100%">
 
+### v3 autonomy presets
+
+The sources being prepared for v3 add a per-Task preset, separate from
+installation and assurance:
+
+| Preset | Product executions per Task | Replans | Replanning models |
+| --- | --- | --- | --- |
+| Essential (`essential`) | 4: 1 initial + 3 repairs | 1 | Sol/high; never automatic Astra |
+| Balanced (`balanced`, new default) | 10: 1 initial + 9 repairs | 3 | Sol/high → Astra/high → Astra/high |
+| Persistent (`persistent`, opt-in) | Unlimited | Unlimited | Sol/high first; Astra/high thereafter |
+
+Merge into `.agents/config/project.yaml`, or select **Autonomy preset** in
+Dashboard **Project settings** and save:
+
+```yaml
+autonomy:
+  version: 1
+  preset: balanced
+```
+
+The durable ledger reserves before managed dispatch; restart or resume does
+not reset the quota. Changes apply to new Tasks. There is no time-based
+abandonment or automatic reduction of acceptance criteria. Persistent may
+consume credits indefinitely until human cancellation; permissions stay unchanged.
+
+A SPEC with ten Balanced Tasks allows up to 100 executions (10 initial +
+90 repairs) and 30 replans; individual tests and internal Calls are not attempts.
+Missing verification/safe conclusion ends as `blocked`; a proven technical
+impediment ends as `failed`. Independent branches remain eligible.
+
+**Current boundary:** counters are enforced in the managed runtime, not on
+external `spawn_agent` calls made directly by Codex. New projects use
+`execution.runtime: managed`: managed PRDs/SPECs and direct standalone Tasks.
+Saving a preset does not invoke a provider. Legacy Tasks need explicit migration
+without resetting consumption. See [autonomy and its guarantees](zaip-aios/guides/19-assurance-e-autonomia.md).
+
 ### Development stack
 
 The development stack describes each responsibility separately, with technology, exact version, and package, image, or service reference. In this project, the contract includes TypeScript, Node.js, Hono, Kysely, PostgreSQL via Supabase, Supabase Auth + Storage, Redis, and BullMQ, keeping development choices recorded alongside project configuration.
@@ -257,7 +305,7 @@ By default, each PRD uses only one SPEC to save resources.
 
 A new SPEC should be created only when a capability can be independently and concurrently implemented and validated. When parts of the work depend on one another, they remain in the same SPEC and are organized by the Task DAG.
 
-In the current runtime, a PRD materializes a deterministic child Execution for each eligible SPEC: its dependencies remain inside the SPEC and its write scopes do not conflict with any other branch. Each child runs with its own coordinator, state, budget quota, and handoff, under a queue bounded by effective parallelism and a single parent invocation ledger; the PRD Execution waits for terminal states, integrates candidates in the parent handoff, and only then applies cross-SPEC validation and finalization. SPECs with external dependencies or scope conflicts remain in the global coordinating DAG.
+In the current runtime, a PRD materializes a deterministic child Execution for each eligible SPEC: its dependencies remain inside the SPEC and its write scopes do not conflict with any other branch. Each child runs with its own coordinator, state, and handoff; in `autonomy-v1`, recovery quotas remain per stable Task, under a queue bounded by effective parallelism and a single parent invocation ledger; the PRD Execution waits for terminal states, integrates candidates in the parent handoff, and only then applies cross-SPEC validation and finalization. SPECs with external dependencies or scope conflicts remain in the global coordinating DAG.
 
 Before a PRD reaches `ready`, Tasks are only work definitions, not yet executing.
 
@@ -294,6 +342,17 @@ Every PRD or SPEC creation is linked to its responsible Run through `creation_ru
 
 Time, tokens, and cost are aggregated whenever this information is available or reconciled. Without sufficient data, values remain `unknown` or `null`.
 
+Overview retains the compact **Estimated cost** card. When coverage is incomplete,
+the accessible description and tooltip explain coverage without an icon. The
+subtitle allocates known spend across the selected task count and recorded hours;
+these are estimated allocation rates, not averages of complete per-task costs.
+Missing costs are not imputed. Each rate independently displays `—` only when its
+denominator is unavailable or zero, without hiding the other valid rate.
+The subtotal is not the full account cost or a bill. Observed
+zero remains zero, while missing measurements remain unavailable. Unexecuted Task
+drafts remain in the work list, outside the executable Kanban stages and operational
+indicators that exclude drafts.
+
 ## Quality and evidence
 
 Quality is part of the definition of done. Each delivery combines tests, review, and checks proportionate to its risk, with objective proof of Acceptance Criteria. Evidence connects approved validations to the Task, Change, Execution, Run, Acceptance Criteria, and candidate. The [review guide](zaip-aios/guides/07-revisao-e-validacao.md) explains how to record the procedure actually executed and its result.
@@ -433,23 +492,31 @@ This progression allows a simple start, adding planning only when breadth, depen
 
 **Technical execution and assurance policies**
 
-Conversation and Task-first preserve the host's manual selection; the project default is not automatically applied to a standalone Task. Automatic policy accepts SPEC/PRD origins configured in `automatic_sources`, with `standard` speed. Model and effort remain fixed in each Run/Sub-Run; ZAIP cannot assume a capability or speed unavailable on the host. See the [model policy](zaip-aios/guides/23-orquestracao-de-modelos.md).
+Conversation and standalone Task principals preserve manual host selection and prefer direct work. When delegation is necessary, disclose that children may use different models/efforts under ZAIP policy; they need not inherit the principal. Model and effort remain fixed per Run, with observed configuration separate from planned selection. Automatic selection requests `standard`; unobserved host capabilities cannot be assumed. See the [model policy](zaip-aios/guides/23-orquestracao-de-modelos.md).
 
 ### Astra policy
 
-Luna, Terra, and Sol remain the routes for simple use and execution. Astra does not execute product work, conduct broad review, or finalize a Task: it is a read-only diagnostic or replanning route, capped at `high` effort. It requires structured signals: an executor attempt that failed on reasoning or a hypothesis plus difficult ambiguity or complexity, or material critical impact accompanied by a difficult diagnosis. Words such as “critical” or “complex”, department, size, or risk alone do not enable it.
+Essential never selects Astra automatically, including children or fallback. Its sole exception is a standalone principal with Astra selected manually by the user. Balanced replans use Sol/high, Astra/high, and Astra/high; in the third block Astra/high may also execute repairs without expanding the quota. Persistent retains that progression without an overall cap.
 
-A Task has at most three cumulative Astra cycles. Each diagnosis returns proof, findings, a cause or hypothesis, a recommended route, scope, a short test/correction plan, and a handback to a Luna, Terra, or Sol executor. Repeated proof or no verifiable progress blocks another cycle. Manual hosts may not let the framework impose model selection; Conversations and Task-first retain that choice. Commercial context is conditional on the request and does not receive technical requirements by default. Historical cost metrics do not promise real savings for a new Task.
+Replanners are isolated and do not edit product files; executor, reviewer, and Gui are distinct roles. Automatic Astra uses only `high`, never replaces review/finalization, and depends on managed dispatch. The old cap of three read-only Astra diagnoses remains only in the legacy contract without `autonomy`; it does not limit Persistent. Context and assurance follow the domain: content needs sources/briefing, engineering needs verified behavior. Real savings must be measured, not inferred from a preset.
 
-Intake correlates the observable turn with the Execution. `prepare` validates the plan without authorizing implementation; `ready` materializes prepared work and `execute` starts authorized delivery. Every delivery and interaction with descendants requires an eligible executor and `zaip-agent-finalizer` last. A read-only interaction without descendants ends after the response, without that circuit. Purely Git publication is an exception: it does not materialize lifecycle records. SPEC/PRD remain active between child Runs and are delivered only through parent gates.
+Intake correlates the observable turn with the Execution. `prepare` validates the plan without authorizing implementation; `ready` materializes prepared work and `execute` starts authorized delivery. Every delivery and delegated interaction requires an eligible executor (or authorized direct Task root) and `zaip-agent-finalizer` last. A read-only interaction without descendants ends after the response, without that circuit. Purely Git publication is an exception: it does not materialize lifecycle records. SPEC/PRD remain active between child Runs and are delivered only through parent gates.
 
-Proof depth is adaptive: a standalone `lite` Task requires at least one typed validation and one Evidence, normally one of each, but accepts legitimate additional proof. `standard` requires two or three validations according to `verification_scope` and at least one consolidated Evidence; `critical` requires three or more, independent review, and persisted risk signals determining additional controls. SPEC and PRD deliveries add a parent matrix, at least three validations and three Evidences, real integration, and independent review. Manual runtime remains the default; autonomy through Codex or Claude is opt-in, isolated in worktrees, and limited by write scopes, commits, budgets, and typed gates. See [Adaptive assurance and opt-in autonomy](zaip-aios/guides/19-assurance-e-autonomia.md).
+Each Task attempt has exactly one responsible orchestrator. Gui is its last
+direct child, a sibling of executors, not a finalizer for every worker.
+The host persists the real decision before canonical Stop; it may relay an
+already-terminal Gui while the responsible Run is open, without requiring
+receipt polling. No decision means no approval. Direct standalone work uses an
+observed Task root with explicit direct authorization; no invented executor,
+and no waiver of Evidence or Gui. See [closure and recovery](zaip-aios/guides/16-lifecycle-e-reconciliacao.md).
+
+Proof depth is adaptive: a standalone `lite` Task requires at least one typed validation and one Evidence, normally one of each, but accepts legitimate additional proof. `standard` requires two or three validations according to `verification_scope` and at least one consolidated Evidence; `critical` requires three or more, independent review, and persisted risk signals determining additional controls. SPEC and PRD deliveries add a parent matrix, at least three validations and three Evidences, real integration, and independent review. New projects default to managed PRDs/SPECs and direct standalone Tasks; Codex or Claude execution requires an explicit request, isolated in worktrees, and limited by write scopes, commits, budgets, and typed gates. See [Adaptive assurance and opt-in autonomy](zaip-aios/guides/19-assurance-e-autonomia.md).
 
 ## Autonomous engineering principles
 
 ZAIP-AIOS combines speed with explicit boundaries. Its principles keep code sustainable, distribute only necessary context, and require proof proportionate to risk.
 
-The schema default is `execution.runtime: manual` when the option is absent; this checkout opted into `autonomous` in `project.yaml`. Configuration does not remove the need for an execution request or authorize publication. Always consult the project's effective file, not just the default described in the guide.
+The schema default is `execution.runtime: manual` when the option is absent; this checkout uses `managed` in `project.yaml`. Configuration does not remove the need for an execution request or authorize publication. Always consult the project's effective file, not just the default described in the guide.
 
 - **Clean Architecture:** domain, application, adapters, and infrastructure remain separate; business rules do not depend on frameworks or external details, dependencies point inward, and composition roots connect concrete implementations at the boundaries.
 - **CQRS:** commands and queries follow explicit, independent flows; commands change state through appropriate use cases and ports, while queries have no side effects and return read models suited to reading.
@@ -470,7 +537,7 @@ Intake captures once per observable turn and reuses valid focus in continuations
 
 This autonomy remains governed: Dave coordinates, each executor receives only the necessary scope, Nanda performs independent review, additional specialists join when objective signals exist, and Gui closes the flow last. The result is a team tailored to the request without unnecessarily multiplying agents and cost.
 
-**Loop Engineering** guides what happens when the first attempt does not satisfy quality criteria. The failure or blocker is classified, the next cycle receives configuration proportionate to the observed difficulty, and every attempt remains auditable. In executions originating from PRD or SPEC, the system can progress from **Luna → Terra → Sol** and from **low → medium → high → xhigh**; Conversations and standalone Tasks preserve the host/Codex manual selection. The model never changes silently within the same Run.
+**Loop Engineering** uses the Task's frozen preset to reserve execution and replanning before the provider, record the result, and choose a corrected route. Balanced allows 1 + 9 executions and three plans: Sol/high → Astra/high → Astra/high; Essential never escalates to Astra, Persistent has no cap. Models never change silently within a Run. A standalone principal's manual preference does not require children to use the same configuration.
 
 ### Summary flow
 
@@ -655,7 +722,7 @@ pnpm build
 
 Before integrating a relevant change or preparing a release, `pnpm verify` runs the complete repository pipeline, including additional tool, contract, generation, workspace, runtime-parity, and release-test gates. This pipeline only validates the lock; if a managed file was intentionally changed, run sync first. Use the pnpm version fixed in `packageManager` (`corepack pnpm` when available). For a bounded change, choose checks appropriate to its risk and diff; the list does not require repeating every test for each documentation edit. Release qualification uses the complete gates in [guide 26](zaip-aios/guides/26-qualidade-e-release.md) on the exact candidate. Do not conflate `validate:github:prepared`, local execution, push, and a green terminal CI.
 
-The public package `@zaip-ai/cli` uses product version `2.2`; npm metadata and SemVer artifacts record it as `2.2.0`. Consult npm to identify the published `latest`. A checkout's version does not prove publication: qualification must record the exact revision, terminal CI result, TGZ integrity, and a fresh installation from the registry. Manual publication with an authorized token is not equivalent to an OIDC attestation. Results and caveats remain in the release Change's evidence, preserving previous attempts.
+This checkout's manifests identify candidate `3.0.0` (product `3.0`). Candidate identity does not mean `latest` has been published or certify production. Release requires the exact revision, terminal CI, TGZ integrity, and a real artifact installation. Attempts and limitations remain in the Change evidence; local results and publication are distinct states.
 
 The detailed architecture is summarized in this README's [Application architecture](#application-architecture) section.
 
@@ -684,10 +751,29 @@ Every GitHub deployment reads `.agents/config/project.yaml`. Set the branch with
 
 ```yaml
 deploy:
-  branch: main
+  # Automated publication: validation environment.
+  branch: beta
+  # Production: human promotion only.
+  production_branch: main
 ```
 
-Replace `main` with a branch such as `production` when needed. If the file or key is absent, the destination is `main`. The current branch and upstream do not replace this configuration. Preflight validates the destination and the agent rereads the file before push using an explicit refspec.
+`beta` is the editable default: use another validation name, such as `staging` or `homolog`, when
+the project needs it. The database uses only `beta`, and production promotion requires a human
+action in GitHub. Frontend and backend follow their configured branch, including `main` when that
+choice is saved in configuration.
+
+`deploy.frontend.branch` and `deploy.backend.branch` are persisted authorization and may be
+`main`. Migrations use only `deploy.database.branch: beta`, with no production fallback.
+Installation does not create a beta environment or cost: verified beta GitHub/Supabase
+integration and informed cost confirmation are prerequisites, and `beta -> main` remains human.
+
+If the person explicitly declines hosted beta, use [manual mode](skills/zaip-skill-database-migrations/references/manual-mode.md): it exports SQL under `db-migrations/` for a human to run in the SQL Editor. The agent, pipeline, and startup never apply that file. Resume dependencies after recorded human success; a human report does not replace independent verification.
+
+Supabase queries use separate `READ-ONLY-BETA` and `READ-ONLY-PROD` contexts, each with its own
+`project_ref`, minimum read permissions, and a credential distinct from the pipeline credential.
+An absent reference, identical destinations, or unproven read-only capability means "not
+configured", with no fallback between environments. MCP snippets document configuration and do
+not create an authenticated connection. See the [deployment and access contract](skills/zaip-skill-backend/references/deployment-environments.md), which uses the [official Supabase MCP format](https://supabase.com/docs/guides/getting-started/mcp).
 
 ### Defense in depth
 

package/templates/.agents/README.md

@@ -8,7 +8,7 @@
 
 O ZAIP-AIOS é um sistema operacional para execução autônoma de trabalho com agentes de IA, que coordena 23 agentes especializados, organizados em 6 squads, dentro do Codex.
 
-Os agentes planejam, executam, revisam, testam e validam o trabalho sob coordenação do orquestrador. A execução autorizada avança até atender aos critérios definidos ou registrar um bloqueio, falha ou limite de orçamento. Dependências externas e decisões fora da autoridade recebida continuam exigindo intervenção humana; autonomia não significa execução indefinida nem garantia de acerto.
+Os agentes planejam, executam, revisam, testam e validam o trabalho sob coordenação do orquestrador. A execução autorizada avança até atender aos critérios ou registrar bloqueio/falha conforme evidências e orçamento. O perfil Persistente permite execução indefinida por escolha explícita; os demais têm cotas por Task. Nenhum perfil garante acerto nem amplia autoridade para ações externas.
 
 Essa abordagem busca reduzir intervenções, contexto desnecessário e retrabalho. Os percentuais de 34% e 62% apresentados adiante se referem a custo médio por tarefa e por hora nas séries históricas ilustradas, respectivamente; não medem diretamente redução de tokens nem garantem economia em uma nova entrega.
 
@@ -53,22 +53,34 @@ No ZAIP-AIOS, uma Task não é considerada concluída apenas porque um agente te
 
 ### Como interpretar esta documentação
 
+Os dois READMEs são mantidos em português e inglês. Na Ajuda do Dashboard,
+o README inglês vem de `README-ENG.md`; guias sem tradução mostram a fonte
+portuguesa atual com aviso de idioma, sem resumos paralelos desatualizados.
+
 Este README e o [handbook](zaip-aios/INDEX.md) descrevem o código-fonte deste repositório. Configuração efetiva, suporte do host, pacote instalado e candidato qualificado são dimensões distintas. `@latest` aponta para a versão publicada, que pode não conter alterações locais. As imagens do Dashboard são ilustrações de estados anteriores, não prova visual do candidato atual.
 
 A atualização documental não aprova uma release. Consulte o [registro de limites de qualificação](https://github.com/zaip-ai/zaip-aios/blob/main/docs/PRODUCTION-COMMERCIAL-READINESS.md#limites-conhecidos-da-qualificação) antes de promover o código; testes locais, paridade, CI e validação em produção devem ser comprovados separadamente.
 
+Na entrega v3, a bateria completa fica na preparação local assinada (`full-v2`). O GitHub verifica o pacote exato, sua instalação e a publicação, sem repetir a bateria de fonte a cada push. A ativação exige qualificação local completa e confiança cadastrada. Há um único smoke automático de instalação antes do npm; checks de fonte e matriz remota ficam manuais, sem teste sobre rascunho privado. Veja o [guia de qualidade e release](zaip-aios/guides/26-qualidade-e-release.md). Lacunas históricas de telemetria permanecem explícitas, sem inventar números ou dispensar testes de dados novos.
+
 ## Instalação em um comando
 
 Com Node.js 22.16.0 ou superior e npm, execute a instalação na raiz do projeto que receberá o ZAIP-AIOS. Em uma instalação nova, o `init` usa o perfil completo (`full`): instala as dependências ausentes da stack e prepara o Terraform. Todos os perfis verificam os runtimes distribuídos e preparam e validam o SQLite local, sem driver separado. Versões de pacotes existentes no projeto são preservadas, com aviso das versões atual e configurada no ZAIP-AIOS:
 
 ```bash
-npx @zaip-ai/cli@latest init
+npx --yes @zaip-ai/cli@latest init --project-only
+node .agents/runtime/bin/zaip.mjs doctor --json
 ```
 
-Também é possível aceitar automaticamente o download inicial do CLI pelo `npx`:
+Esses são os dois passos do primeiro resultado verificável: `init` instala o
+framework no projeto selecionado sem alterar a configuração global do Codex, e
+`doctor --json` confirma o layout, checksums e adapters instalados. O resultado
+só está pronto quando o JSON retornar `"valid": true`.
+
+Antes de escrever no projeto, revise o plano:
 
 ```bash
-npx --yes @zaip-ai/cli@latest init
+npx --yes @zaip-ai/cli@latest init --project-only --dry-run
 ```
 
 Os dois comandos usam o perfil salvo no projeto ou `full` quando ainda não existe uma escolha. A opção `--yes` antes do nome do pacote apenas aceita o download inicial do CLI pelo `npx`; ela não força a substituição de dependências, arquivos ou versões já existentes.
@@ -238,6 +250,42 @@ A configuração da plataforma apresenta o estado de ativação do ZAIP-AIOS e u
 
 <img src="https://raw.githubusercontent.com/zaip-ai/zaip-aios/main/.agents/config/src/dashboard_pt_configuracao_plataforma.png" alt="Dashboard ZAIP-AIOS, configuração da plataforma" width="100%">
 
+### Perfis de autonomia da v3
+
+As fontes em preparação para a v3 acrescentam um preset por Task, separado de
+instalação e assurance:
+
+| Perfil | Execuções de produto por Task | Replanejamentos | Modelos dos replanejamentos |
+| --- | --- | --- | --- |
+| Essencial (`essential`) | 4: 1 inicial + 3 reparações | 1 | Sol/high; nunca Astra automático |
+| Equilibrado (`balanced`, padrão novo) | 10: 1 inicial + 9 reparações | 3 | Sol/high → Astra/high → Astra/high |
+| Persistente (`persistent`, opt-in) | Sem teto | Sem teto | Sol/high primeiro; Astra/high nos seguintes |
+
+Mescle no arquivo `.agents/config/project.yaml` ou selecione **Perfil de
+autonomia** em **Configurações do projeto** no Dashboard e salve:
+
+```yaml
+autonomy:
+  version: 1
+  preset: balanced
+```
+
+O diário durável reserva antes do despacho gerenciado; reiniciar ou retomar
+não zera a quota. A alteração vale para novas Tasks. Não há abandono por tempo
+nem redução automática de critérios de aceite. Persistente pode consumir
+créditos indefinidamente até cancelamento humano; não amplia permissões.
+
+Uma SPEC de dez Tasks Equilibradas admite até 100 execuções (10 iniciais +
+90 reparações) e 30 replanejamentos; testes e Calls internas não são tentativas.
+A falta de verificação/conclusão segura termina `blocked`; impedimento técnico
+comprovado termina `failed`. Ramos independentes continuam elegíveis.
+
+**Limite atual:** os contadores são impostos no runtime gerenciado, não em
+`spawn_agent` externo feito diretamente pelo Codex. Novos projetos usam
+`execution.runtime: managed`: PRD/SPEC gerenciados e avulsas diretas. Salvar
+o preset não inicia provider. Legados exigem migração explícita, sem zerar
+consumo. Veja [autonomia e suas garantias](zaip-aios/guides/19-assurance-e-autonomia.md).
+
 ### Stack de desenvolvimento
 
 A stack de desenvolvimento descreve cada responsabilidade separadamente, com tecnologia, versão exata e referência do pacote, imagem ou serviço. No projeto, esse contrato inclui TypeScript, Node.js, Hono, Kysely, PostgreSQL via Supabase, Supabase Auth + Storage, Redis e BullMQ, permitindo que as escolhas de desenvolvimento permaneçam registradas junto da configuração do projeto.
@@ -277,7 +325,7 @@ Por padrão, cada PRD utiliza apenas uma SPEC, buscando economia.
 
 Uma nova SPEC só deve ser criada quando existir uma capacidade que possa ser implementada e validada de forma independente e paralela. Quando existe dependência entre partes do trabalho, elas permanecem na mesma SPEC e são organizadas pela DAG de Tasks.
 
-No runtime atual, um PRD materializa uma Execution-filho determinística para cada SPEC elegível: suas dependências permanecem dentro da SPEC e seus write scopes não conflitam com nenhum outro ramo. Cada filha executa com coordinator, estado, quota de orçamento e handoff próprios, sob uma fila limitada pelo paralelismo efetivo e por um ledger parental único de invocações; a Execution do PRD aguarda os estados terminais, integra os candidatos no handoff parental e só então aplica validação cross-SPEC e finalização. SPECs com dependência externa ou conflito de escopo permanecem na DAG global coordenadora.
+No runtime atual, um PRD materializa uma Execution-filho determinística para cada SPEC elegível: suas dependências permanecem dentro da SPEC e seus write scopes não conflitam com nenhum outro ramo. Cada filha executa com coordinator, estado e handoff próprios; em `autonomy-v1`, a quota de recuperação continua por Task estável, sob uma fila limitada pelo paralelismo efetivo e por um ledger parental único de invocações; a Execution do PRD aguarda os estados terminais, integra os candidatos no handoff parental e só então aplica validação cross-SPEC e finalização. SPECs com dependência externa ou conflito de escopo permanecem na DAG global coordenadora.
 
 Antes de o PRD chegar ao estado `ready`, as Tasks são apenas definições de trabalho, ainda sem execução.
 
@@ -314,6 +362,17 @@ Toda criação de PRD ou SPEC é vinculada à Run responsável por meio do campo
 
 Tempo, tokens e custo são agregados sempre que essas informações estiverem disponíveis ou forem reconciliadas. Quando não houver dados suficientes, os valores permanecem como `unknown` ou `null`.
 
+Na Visão geral, uma cobertura incompleta não esconde a soma disponível: o Dashboard
+mantém o cartão compacto **Custo Estimado**, sem ícone. A descrição acessível e o
+tooltip informam a cobertura. O subtítulo divide o subtotal conhecido pelo número
+de tarefas e pelas horas registradas no mesmo recorte: são taxas estimadas de
+alocação, não médias de custos completos por tarefa. Com cobertura parcial, não
+estima os valores ausentes. Cada taxa fica `—` apenas se sua base estiver indisponível
+ou for zero; uma taxa válida não é escondida porque a outra está indisponível.
+O subtotal não é o custo integral nem a fatura da conta. Zero observado continua sendo zero;
+ausência de medição continua indisponível. Rascunhos de Task ficam na lista de
+trabalho, fora do Kanban executável e dos indicadores operacionais sem rascunhos.
+
 
 ## Qualidade e evidências
 
@@ -462,24 +521,33 @@ Essa progressão permite começar de forma simples e acrescentar planejamento ap
 
 **Políticas técnicas de execução e assurance**
 
-Conversation e Task-first preservam a seleção manual do host; o default do projeto não é aplicado automaticamente a uma Task avulsa. A política automática aceita origens SPEC/PRD configuradas em `automatic_sources`, com velocidade `standard`. Modelo e effort ficam fixos em cada Run/Sub-Run; capacidade ou velocidade indisponível no host não pode ser presumida pelo ZAIP. Consulte a [política de modelos](zaip-aios/guides/23-orquestracao-de-modelos.md).
+Conversation e o principal de Task avulsa preservam a seleção manual do host, priorizando trabalho direto. Quando delegar for necessário, informe que os filhos podem usar modelos/esforços diferentes pela política ZAIP; não há obrigação de herdar o principal. Modelo e effort ficam fixos por Run, com observação efetiva separada da seleção planejada. A seleção automática solicita `standard`; capacidade não observada do host não pode ser presumida. Consulte a [política de modelos](zaip-aios/guides/23-orquestracao-de-modelos.md).
 
 ### Política Astra
 
-Luna, Terra e Sol permanecem as rotas de uso simples e de execução. Astra não executa produto, não faz revisão geral nem finaliza uma Task: é uma rota read-only de diagnóstico ou replanejamento, com effort `high` como teto. Ela só pode ser usada após sinais estruturados — tentativa executora com falha de raciocínio/hipótese e ambiguidade ou complexidade difícil, ou impacto crítico material acompanhado de diagnóstico difícil. Palavras como “crítico” ou “complexo”, departamento, tamanho ou risco isolado não a habilitam.
+No Essencial, Astra nunca é selecionado automaticamente, inclusive em filhos ou fallback. A única exceção é o principal avulso com Astra escolhido manualmente pelo usuário. No Equilibrado, os três replanejamentos usam Sol/high, Astra/high e Astra/high; no terceiro bloco Astra/high também pode executar a reparação, sem ampliar a quota. Persistente mantém essa progressão sem teto total.
 
-Há no máximo três ciclos Astra cumulativos por Task. Cada diagnóstico produz provas, findings, causa ou hipótese, rota recomendada, escopo, plano curto de teste/correção e handback para executor Luna, Terra ou Sol. Prova repetida ou falta de progresso bloqueia novo ciclo. Hosts manuais podem não permitir que o framework imponha a seleção; Conversations e Task-first preservam essa escolha. Contexto comercial é condicional ao pedido e não recebe requisitos técnicos por padrão. Métricas históricas de custo não prometem economia real em uma nova Task.
+O replanejador é isolado e não edita produto; executor, revisor e Gui são papéis distintos. Astra automático usa somente `high`, não substitui revisão/finalização e depende do despacho gerenciado. A regra antiga de até três diagnósticos Astra somente leitura permanece apenas no contrato legado sem `autonomy`; não limita Persistente. Contexto e assurance seguem o domínio: conteúdo exige fontes/briefing, engenharia exige comportamento verificável. Economia real precisa ser medida, não inferida do preset.
 
-O intake correlaciona o turno observável à Execution. `prepare` valida o plano, sem autorizar implementação; `ready` materializa trabalho preparado e `execute` inicia a entrega autorizada. Toda delivery e interaction com descendentes exigem executor elegível e `zaip-agent-finalizer` por último. Interaction read-only sem descendentes termina após a resposta, sem esse circuito. Publicação puramente Git é uma exceção: não materializa lifecycle. SPEC/PRD permanecem ativos entre Runs filhas e só são entregues por gates parentais.
+O intake correlaciona o turno observável à Execution. `prepare` valida o plano, sem autorizar implementação; `ready` materializa trabalho preparado e `execute` inicia a entrega autorizada. Toda delivery e interaction delegada exige executor elegível (ou raiz Task direta autorizada) e `zaip-agent-finalizer` por último. Interaction read-only sem descendentes termina após a resposta, sem esse circuito. Publicação puramente Git é uma exceção: não materializa lifecycle. SPEC/PRD permanecem ativos entre Runs filhas e só são entregues por gates parentais.
 
-A profundidade de prova é adaptativa: Task standalone `lite` exige no mínimo uma validação tipada e uma Evidence, normalmente uma de cada, mas aceita provas adicionais legítimas. `standard` exige duas ou três validações conforme `verification_scope` e pelo menos uma Evidence consolidada; `critical` exige três ou mais, revisão independente e os sinais de risco persistidos que determinam controles adicionais. Entregas de SPEC e PRD acrescentam matriz parental, pelo menos três validações e três Evidences, integração real e revisão independente. O runtime manual continua padrão; a autonomia por Codex ou Claude é opt-in, isolada em worktrees e limitada por write scopes, commits, budgets e gates tipados. Consulte [Assurance adaptativa e autonomia opt-in](zaip-aios/guides/19-assurance-e-autonomia.md).
+Cada tentativa de Task tem exatamente um orquestrador responsável. Gui é seu
+último filho direto, irmão dos executores, não finalizador de cada trabalhador.
+O host persiste a decisão real antes do Stop canônico; pode retransmitir Gui
+já terminal enquanto o responsável estiver aberto, sem obrigá-lo a esperar
+recibos. Ausência de decisão não é aprovação. A preferência por execução
+avulsa direta usa uma raiz observada com `--direct-authorization REFERÊNCIA`
+explícita; não cria executor fictício nem dispensa Evidence e Gui. Veja
+[fechamento e recuperação](zaip-aios/guides/16-lifecycle-e-reconciliacao.md).
+
+A profundidade de prova é adaptativa: Task standalone `lite` exige no mínimo uma validação tipada e uma Evidence, normalmente uma de cada, mas aceita provas adicionais legítimas. `standard` exige duas ou três validações conforme `verification_scope` e pelo menos uma Evidence consolidada; `critical` exige três ou mais, revisão independente e os sinais de risco persistidos que determinam controles adicionais. Entregas de SPEC e PRD acrescentam matriz parental, pelo menos três validações e três Evidences, integração real e revisão independente. Novos projetos usam runtime gerenciado para PRD/SPEC e direto para avulsas; a execução por Codex ou Claude é autorizada por pedido, isolada em worktrees e limitada por write scopes, commits, budgets e gates tipados. Consulte [Assurance adaptativa e autonomia opt-in](zaip-aios/guides/19-assurance-e-autonomia.md).
 
 
 ## Princípios de engenharia autônoma
 
 O ZAIP-AIOS combina velocidade com limites explícitos. Seus princípios mantêm o código sustentável, distribuem apenas o contexto necessário e exigem comprovação proporcional ao risco.
 
-O padrão do schema é `execution.runtime: manual` quando a opção está ausente; este checkout optou por `autonomous` em `project.yaml`. A configuração não dispensa pedido de execução nem autoriza publicar. Consulte sempre o arquivo efetivo do projeto, não apenas o default descrito no guia.
+O padrão do schema é `execution.runtime: manual` quando a opção está ausente; este checkout usa `managed` em `project.yaml`. A configuração não dispensa pedido de execução nem autoriza publicar. Consulte sempre o arquivo efetivo do projeto, não apenas o default descrito no guia.
 
 - **Clean Architecture:** domínio, aplicação, adapters e infraestrutura permanecem separados; regras de negócio não dependem de frameworks ou detalhes externos, as dependências apontam para as camadas internas e composition roots conectam implementações concretas nas bordas.
 - **CQRS:** commands e queries seguem fluxos explícitos e independentes; comandos alteram estado por casos de uso e ports apropriados, enquanto consultas não produzem efeitos colaterais e retornam read models adequados à leitura.
@@ -500,7 +568,7 @@ O **Graph Engineering** transforma uma entrega complexa em uma sequência coorde
 
 Essa autonomia permanece governada: Dave coordena, cada executor recebe apenas o escopo necessário, Nanda realiza a revisão independente, especialistas adicionais entram quando existem sinais objetivos e Gui encerra o fluxo por último. O resultado é uma equipe ajustada à demanda, sem multiplicar agentes e custo sem necessidade.
 
-O **Loop Engineering** orienta o que acontece quando a primeira tentativa não satisfaz os critérios de qualidade. A falha ou o bloqueio é classificado, o próximo ciclo recebe uma configuração proporcional à dificuldade observada e cada tentativa permanece auditável. Em execuções originadas de PRD ou SPEC, o sistema pode evoluir de **Luna → Terra → Sol** e de **low → medium → high → xhigh**; Conversations e Tasks avulsas preservam a seleção manual do host/Codex. O modelo nunca muda silenciosamente dentro da mesma Run.
+O **Loop Engineering** usa o perfil congelado da Task para reservar execução e replanejamento antes do provider, registrar o resultado e escolher uma rota corrigida. No Equilibrado são 1 + 9 execuções e três planos Sol/high → Astra/high → Astra/high; Essencial não escala para Astra, Persistente não tem teto. O modelo não muda silenciosamente dentro da mesma Run. A preferência manual do principal avulso não obriga seus filhos a usar a mesma configuração.
 
 ### Fluxo resumido
 
@@ -689,7 +757,7 @@ Antes de integrar uma mudança relevante ou preparar um release, `pnpm verify` e
 
 Use a versão de pnpm fixada em `packageManager` (`corepack pnpm` quando disponível). Para uma alteração delimitada, selecione os checks pertinentes ao risco e ao diff; a lista acima não exige repetir todos os testes a cada edição documental. Qualificação de release usa os gates completos do [guia 26](zaip-aios/guides/26-qualidade-e-release.md) no candidato exato. Não confunda `validate:github:prepared`, execução local, push e CI terminal verde.
 
-O pacote público `@zaip-ai/cli` usa a versão de produto `2.2`; nos metadados npm e nos artefatos SemVer ela é registrada como `2.2.0`. Consulte o npm para identificar o `latest` publicado. A versão em um checkout não comprova publicação: a qualificação deve registrar a revisão exata, o resultado terminal do CI, a integridade do TGZ e uma instalação nova do registro. Publicação manual com token autorizado não equivale a atestado OIDC. Resultados e ressalvas ficam nas evidências da Change de release, preservando as tentativas anteriores.
+Os manifests deste checkout registram o candidato `3.0.0` (produto `3.0`). A identificação do candidato não significa que o `latest` já foi publicado nem certifica produção. A release exige revisão exata, CI terminal, integridade do TGZ e instalação real do artefato. Tentativas e limitações ficam nas evidências da Change; resultados locais e publicação são estados distintos.
 
 A arquitetura detalhada está resumida na seção [Arquitetura das aplicações](#arquitetura-das-aplicações) deste README.
 
@@ -731,12 +799,29 @@ Todo deploy GitHub consulta `.agents/config/project.yaml`. Para escolher a branc
 
 ```yaml
 deploy:
-  branch: main
+  # Publicação automatizada: ambiente de validação.
+  branch: beta
+  # Produção: somente promoção humana.
+  production_branch: main
 ```
 
-Troque `main` por outra branch, como `production`, quando necessário. Se o arquivo ou a chave
-não existir, o destino será `main`. A branch atual e o upstream não substituem essa configuração.
-O preflight valida o destino e o agente relê o arquivo antes do push, usando um refspec explícito.
+`beta` é o padrão editável: use outro nome de validação, como `staging` ou `homolog`, se o
+projeto precisar. O banco usa somente `beta` e a promoção para produção requer ação humana no
+GitHub. Frontend e backend seguem sua branch configurada, inclusive `main` quando essa escolha
+estiver salva na configuração.
+
+`deploy.frontend.branch` e `deploy.backend.branch` são autorização persistida e podem ser `main`.
+Migrations usam somente `deploy.database.branch: beta`, sem fallback para produção. A instalação
+não cria ambiente beta nem custo: integração GitHub/Supabase beta verificada e confirmação
+informada de custo são pré-requisitos; a promoção `beta -> main` continua humana.
+
+Se a pessoa recusar explicitamente a beta hospedada, use o [modo manual](skills/zaip-skill-database-migrations/references/manual-mode.md): ele exporta SQL em `db-migrations/` para execução humana no SQL Editor. O agente, pipeline e startup não aplicam esse arquivo. Após sucesso humano registrado, retome as dependências; o relato humano não substitui comprovação independente.
+
+Consultas Supabase usam contextos separados `READ-ONLY-BETA` e `READ-ONLY-PROD`, cada qual com
+`project_ref` próprio, permissões mínimas de leitura e credencial distinta da credencial do
+pipeline. Referência ausente, destinos iguais ou capacidade read-only não demonstrada significam
+"não configurado", sem fallback entre ambientes. Os snippets MCP documentam configuração e não
+criam conexão autenticada. Consulte o [contrato de ambientes e acessos](skills/zaip-skill-backend/references/deployment-environments.md), que usa o formato do [MCP oficial do Supabase](https://supabase.com/docs/guides/getting-started/mcp).
 
 ### Defesa em profundidade
 

package/templates/.agents/architecture/software-architecture.md

@@ -1,61 +1,3 @@
----
-schema_version: 1
-kind: software-architecture
-generated_from: .agents/config/project.yaml
----
-
 # Arquitetura de Software
 
-> Arquitetura padrão ZAIP-AIOS. Atualize este documento quando as decisões técnicas do projeto mudarem.
-
-## Projeto
-
-- **Nome:** {{PROJECT_NAME}}
-- **ID:** {{PROJECT_ID}}
-
-## Perfil técnico padrão
-
-- **Stack profile:** zaip-aios-stack
-- **Linguagem:** TypeScript
-- **API:** Hono
-- **Query builder:** Kysely
-- **Runtime de execução:** manual
-
-## Superfícies e serviços padrão
-
-| Responsabilidade | Tecnologia padrão |
-| --- | --- |
-| Web App | React e Vite |
-| Site e landing pages | Astro e React Islands |
-| Dados, autenticação e armazenamento | PostgreSQL via Supabase |
-| Cache, locks e estado temporário | Redis |
-| Filas, workers e retries | BullMQ |
-| Infraestrutura | Terraform |
-
-## Layout do código
-
-| Papel | Caminho |
-| --- | --- |
-| frontend | apps/frontend |
-| backend | apps/backend |
-| site | apps/site |
-| modules | modules |
-| packages | packages |
-| e2e | tests/e2e |
-
-## Invariantes
-
-- clean-architecture
-- cqrs
-- module-storage-private
-
-## Decisões a definir pelo projeto
-
-Registre aqui os provedores, versões, infraestrutura, integrações e decisões de domínio adotados por este projeto. O instalador não herda versões, provedores ou overrides do repositório ZAIP-AIOS.
-
-## Comandos de validação
-
-| Comando | Execução |
-| --- | --- |
-| test | `corepack pnpm test` |
-| typecheck | `corepack pnpm typecheck` |
+Em construção.

package/templates/.agents/branding/brandbook.md

@@ -0,0 +1,3 @@
+# Brandbook
+
+Em construção.