@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/zaip-aios/guides/05-prds.md

@@ -6,8 +6,33 @@ Use PRD para uma iniciativa de produto com multiplas capacidades ou SPECs.
 2. Delimite escopo, restricoes e nao objetivos.
 3. Mantenha o PRD agnostico de linguagem, framework, banco, infraestrutura e fornecedor; tecnologia imposta externamente entra como restricao de negocio, nao como desenho da solucao.
 4. Especifique requisitos funcionais e nao funcionais.
-5. Converta capacidades em SPECs independentes, onde a stack tecnica sera resolvida.
+5. Use uma SPEC por padrão. Crie outra somente para capacidade implementável e verificável em paralelo, sem dependência entre SPECs; dependências ficam nas Tasks internas.
 6. Relacione riscos, rollout, observabilidade e rollback.
 7. Monte a DAG e confirme que todo aceite possui evidencia planejada.
 8. Mantenha PRD e SPECs selecionadas em Execucao enquanto restar trabalho; Runs filhas fecham Tasks, nao o macro.
 9. Conclua somente depois das Tasks, integracao, outcomes e gates parentais.
+
+## Intenções
+
+- “Me ajude a pensar sobre um PRD”: Conversation, sem artefato.
+- “Crie um PRD”: até cinco perguntas críticas por turno e no máximo três turnos; depois persiste PRD, SPECs e PreparedPlan `draft`, vincula a Run e o `creation_run_id` ao macro e não cria Tasks reais. Duração, tokens e custo só são agregados quando observados ou reconciliados.
+- “Deixe pronto para executar” ou “finalize/conclua esse PRD” em `draft`: lapida, valida e materializa SPECs/Tasks/Changes/Execution como `ready|planned`, sem executar.
+- “Execute esse PRD”: executa todas as SPECs selecionadas. Pedido dirigido a SPEC ou Task usa o menor grão.
+- “Implemente”: sem alvo abre apenas uma Conversation de planejamento; em `draft` finaliza o plano; em `ready` executa; em `active|blocked|failed` continua, retoma ou cria rework.
+- “Desenvolva/melhore/aprimore”: sempre planeja/refina/rework e nunca executa automaticamente.
+
+PRD cancelado permanece imutável. Novo planejamento cria sucessor `draft`, tag `rework` e `rework_of_prd_id`.
+
+## Quantas SPECs criar
+
+| SPECs | Quando usar | Exemplo |
+| --- | --- | --- |
+| 1 | Padrão; há sequência, contrato em evolução ou dependência entre frentes. | Recuperação de senha completa em uma DAG. |
+| 2 | Duas capacidades paralelas contra contrato estável e escopos separados. | Web e Mobile contra API congelada. |
+| 3 | Três capacidades entregáveis isoladamente; integração fica no PRD. | Identidade, cobrança e notificações. |
+| 4 | Quatro adaptadores independentes, com ownership e diretórios distintos. | Adaptadores fiscais de quatro países. |
+| 5 | Exceção: cinco implementações simétricas do mesmo contrato validado. | Email, SMS, WhatsApp, Push e Inbox. |
+
+Qualquer dependência técnica entre duas frentes obriga reuni-las na mesma SPEC e expressar a ordem entre Tasks. Mais de cinco exige recortar o PRD ou registrar uma decisão de exceção.
+
+Toda Execution originada por PRD usa velocidade `standard` em todas as SPECs, Tasks, Runs e Sub-Runs descendentes. Não existe skill, hook ou override de Fast para esse fluxo. A única execução de produto mais rápida suportada é Task-first realmente independente, com Fast selecionado manualmente no Codex; uma urgência não autoriza remover a estrutura necessária de PRD/SPEC.

package/templates/.agents/zaip-aios/guides/06-execucao.md

@@ -11,3 +11,13 @@
 9. Execute os gates finais e documente rollback.
 
 Nao marque conclusao por esforco: conclua pelo resultado verificavel. Gate insuficiente ou finalizador ausente usa blocked; erro tecnico impeditivo usa failed; cancelamento exige pedido explicito.
+
+`execute` respeita o menor grão nomeado: Task executa um nó elegível; SPEC executa sua DAG; PRD executa todas as SPECs selecionadas. “Conclua a execução” ou “finalize a implementação” em trabalho ativo continua Tasks e gates, mas nunca força sucesso. “Desenvolva/melhore/aprimore” volta a planejamento/rework e exige nova promoção.
+
+## Modelo, effort e velocidade por origem
+
+- Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex.
+- Fast para execução de produto é suportado somente em Task-first realmente independente e deve ser selecionado manualmente no Codex.
+- Executions originadas por SPEC ou PRD usam sempre velocidade `standard`, inclusive em todas as Tasks, Runs e Sub-Runs descendentes.
+- O ZAIP não ativa, persiste ou herda Fast por skill, hook, PreparedPlan ou override de Execution.
+- Selecionar uma Task descendente como menor grão não a transforma em Task-first nem remove a velocidade `standard` herdada do macro.

package/templates/.agents/zaip-aios/guides/08-contexto-e-tokens.md

@@ -1,6 +1,6 @@
 # Contexto e tokens
 
-1. Comece por `project.yaml`, `core.md` e projections de runtime.
+1. Comece por `project.yaml`, `core.md` e pelos manifests de `.agents/records/lifecycle/`.
 2. Carregue somente a Rule, Requirement ou skill acionada.
 3. Prefira indices, resumos e busca direcionada a arquivos completos.
 4. Abra records apenas por lifecycle ID conhecido.

package/templates/.agents/zaip-aios/guides/11-observabilidade-e-custos.md

@@ -8,3 +8,5 @@
 6. Converta achados recorrentes em Rule, Requirement ou melhoria de skill.
 
 Run e o envelope da chamada do `zaip-agent-orchestrator`; `parent_run_id` nulo identifica esse nivel. Sub-Run e a chamada de qualquer subagente e possui `parent_run_id`. Ambas fixam modelo e effort e agregam Calls, segmentos de uso, tokens e custo. Calls nao possuem tela ou lifecycle proprio. Operacao e Monitor de Custos apresentam “Chamadas do agente orquestrador” e “Chamadas de subagentes”; a Execution soma as duas categorias, finalizadores e Calls sem dupla contagem. Cada segmento de uso possui uma chave de origem e so pode ser atribuido uma vez; uma correcao de duplicidade registra supersessao e preserva o evento historico. Inspecione `run_purpose`, pai e `agent_name`; agentes do catalogo usam `zaip-agent-*`. Diferencie status tecnico da chamada de agente e resultado terminal da Task. Reconcilie lifecycle globalmente apenas por comando humano explicito ou pelo popup confirmado; isso nao ocorre em cada turno nem ao abrir o dashboard.
+
+A criação explícita de PRD/SPEC vincula a Run de definição e o `creation_run_id` ao macro. Duração, tokens e custo aparecem no PRD/SPEC antes de existirem Tasks somente quando foram observados ou reconciliados; valores indisponíveis permanecem `null`. Pensar sem criar permanece apenas em Conversas. Nunca atribua telemetria indisponível nem transforme ausência em zero.

package/templates/.agents/zaip-aios/guides/13-boas-praticas.md

@@ -10,3 +10,6 @@
 - Nunca termine a Run raiz sem o Sub-Run finalizador ou com Task em executing/verifying.
 - Nao terminalize SPEC/PRD por causa do resultado isolado de uma Task filha.
 - Prefira reconciliacao manual sob demanda; hooks de escrita fazem checagem local sem varredura global.
+- Use uma SPEC por padrão; divida somente capacidades realmente independentes e paralelizáveis.
+- Não crie Tasks durante definição: mostre blueprints compactos e materialize somente em `ready|execute`.
+- Resolva verbos de lifecycle pelo alvo e status persistido, nunca por palavra isolada.

package/templates/.agents/zaip-aios/guides/14-troubleshooting.md

@@ -4,9 +4,11 @@
 2. Leia a mensagem completa e identifique o primeiro erro causal.
 3. Rode doctor, validadores focados e `git diff --check`.
 4. Confira versoes, paths, encoding, variaveis e arquivos gerenciados.
-5. Compare com projections de runtime, sem varrer records.
+5. Compare `manifest.json`, `summary.json`, índices e chunks de `records/lifecycle`, sem varrer records.
 6. Corrija a causa, repita a reproducao e depois os gates completos.
 
 Se uma Task estiver presa em executing/verifying, use o popup Reconciliar. O reparo aceita `task_complete` exato, marca Run orfa apos dez minutos como failed e usa blocked quando faltam gates; nunca infere cancelamento. Nao habilite reconciliacao automatica por turno ou na abertura do dashboard.
 
 Se o problema for de instalacao ou integridade, consulte `framework.lock.yaml`.
+
+Se “finalizar” tentou entregar um PRD `draft`, confira adapters/skills: o correto é lapidar e mover para `ready`. Se uma DAG nova cruza SPECs, una as capacidades em uma SPEC e mantenha a dependência entre suas Tasks. PRD cancelado não reabre; crie sucessor `rework`.

package/templates/.agents/zaip-aios/guides/16-lifecycle-e-reconciliacao.md

@@ -7,6 +7,8 @@
 - SPEC: planejamento tecnico de multiplas Tasks; draft fica em Planejamento.
 - PRD: definicao de produto; draft fica em Definicao.
 
+Pensar/explorar PRD ou SPEC é Conversation. Criar explicitamente persiste macro, SPECs e PreparedPlan `draft`, atribui telemetria e mantém apenas blueprints de Tasks. `ready` é o único ponto que materializa Tasks/Changes/Execution sem iniciar; `execute` materializa e inicia.
+
 ## Colunas
 
 | Coluna | Entidades |
@@ -32,10 +34,14 @@ O ultimo filho de qualquer Execution e sempre o `zaip-agent-finalizer`. Ele agua
 
 `blocked` e retomavel com `task resume`; `failed` exige `task rework` na mesma Task e nova tentativa. `completed` e `cancelled` sao imutaveis. Interromper geracao bloqueia; cancelar a Task explicitamente cancela.
 
+`finalize|conclua` em macro `draft|ready` significa lapidar e deixar pronto; em trabalho ativo, “conclua a execução/finalize a implementação” continua Tasks e gates. `implemente` é sensível ao estado; `desenvolva|melhore|aprimore` sempre planeja/refina/rework. PRD cancelado gera sucessor vinculado com tag `rework`.
+
 ## SPEC e PRD
 
 Ao iniciar a primeira Task filha, os pais ficam active/Execucao e permanecem assim entre Runs. Task bloqueada ou falhada nao bloqueia automaticamente o pai. Depois que todas as Tasks concluem, SPEC/PRD entram em verificacao parental; apenas gates de integracao, Acceptance Criteria, outcomes e Evidence entregam o macro.
 
+Novas SPECs de um PRD não possuem dependências entre si: são capacidades paralelizáveis e verificáveis isoladamente. Dependências e ordem ficam nas Tasks da mesma SPEC; integração final é gate parental.
+
 ## Reconciliacao
 
 O popup Reconciliar chama `run reconcile --open` somente depois da confirmacao humana. Nao existe varredura ao abrir o dashboard, por turno ou por intervalo.
@@ -44,4 +50,4 @@ O reparo e idempotente: `task_complete` local exato permite tentar conclusao; ga
 
 ## Mutacoes
 
-Codigo, documentacao e configuracao exigem Task materializada e Run raiz ativa antes da escrita. Sao isentos deploy/publicacao Git sem mudanca de produto, records/projections/telemetria ZAIP, metadados `.git`, caches, builds, testes e temporarios descartaveis. O hook pre-write faz checagem local do turno, sem tokens e sem reconciliacao global.
+Codigo, documentacao e configuracao exigem Task materializada e Run raiz ativa antes da escrita. Sao isentos deploy/publicacao Git sem mudanca de produto, manifests e telemetria ZAIP gerados pelo lifecycle, metadados `.git`, caches, builds, testes e temporarios descartaveis. O hook pre-write faz checagem local do turno, sem tokens e sem reconciliacao global.

package/templates/.local/gitignore.template

@@ -0,0 +1,2 @@
+*
+!.gitignore