@zaip-ai/cli 0.1.0 → 1.0.2

package/templates/.zaip-aios/schemas/contracts.schema.json

@@ -0,0 +1,243 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zaip.aios/schemas/contracts.schema.json",
+  "oneOf": [
+    {
+      "title": "ProjectConfig",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "project",
+        "stack",
+        "clients",
+        "tracking"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 1
+        },
+        "project": {
+          "type": "object"
+        },
+        "stack": {
+          "type": "object"
+        },
+        "clients": {
+          "type": "object"
+        },
+        "tracking": {
+          "type": "object"
+        }
+      }
+    },
+    {
+      "title": "FrameworkLock",
+      "type": "object",
+      "required": [
+        "lock_version",
+        "framework",
+        "layout",
+        "resolved_profile",
+        "managed_files"
+      ],
+      "properties": {
+        "lock_version": {
+          "enum": [
+            1,
+            2
+          ]
+        },
+        "framework": {
+          "type": "object"
+        },
+        "layout": {
+          "type": "object",
+          "required": [
+            "version"
+          ],
+          "properties": {
+            "version": {
+              "enum": [
+                2,
+                3
+              ]
+            }
+          }
+        },
+        "resolved_profile": {
+          "type": "object"
+        },
+        "managed_files": {
+          "type": "object"
+        }
+      }
+    },
+    {
+      "title": "PRD",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "id",
+        "revision",
+        "title",
+        "status",
+        "problem"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^PRD-"
+        },
+        "revision": {},
+        "title": {},
+        "status": {},
+        "problem": {}
+      }
+    },
+    {
+      "title": "SPEC",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "id",
+        "revision",
+        "title",
+        "status",
+        "objective"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^SPEC-"
+        },
+        "revision": {},
+        "title": {},
+        "status": {},
+        "objective": {}
+      }
+    },
+    {
+      "title": "Task",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "id",
+        "change_id",
+        "status",
+        "requirement_ids"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^TASK-"
+        },
+        "change_id": {},
+        "status": {},
+        "requirement_ids": {}
+      }
+    },
+    {
+      "title": "Change",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "id",
+        "status",
+        "source",
+        "task_ids"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^CHG-"
+        },
+        "status": {},
+        "source": {},
+        "task_ids": {}
+      }
+    },
+    {
+      "title": "Execution",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "id",
+        "origin",
+        "status",
+        "dag"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^EXEC-"
+        },
+        "origin": {},
+        "status": {},
+        "dag": {}
+      }
+    },
+    {
+      "title": "Run",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "run_id",
+        "phase",
+        "entrypoint",
+        "storage_mode"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "run_id": {
+          "type": "string",
+          "pattern": "^RUN-"
+        },
+        "phase": {},
+        "entrypoint": {},
+        "storage_mode": {}
+      }
+    },
+    {
+      "title": "Decision",
+      "type": "object",
+      "required": [
+        "schema_version",
+        "id",
+        "scope_type",
+        "origin",
+        "decision",
+        "reason"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 2
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^DEC-(?:HUMAN|AI)-"
+        },
+        "scope_type": {},
+        "origin": {},
+        "decision": {},
+        "reason": {}
+      }
+    }
+  ]
+}

package/templates/.zaip-aios/templates/config/agents/catalog.yaml

@@ -0,0 +1,246 @@
+schema_version: 1
+agents:
+  - id: agent-orchestrator
+    version: 1
+    purpose: Resolve the DAG and delegate only to capable least-privilege agents.
+    codex_name: zaip-agent-orchestrator
+    nickname_candidates: [zaip-agent-Atlas, zaip-agent-Conductor, zaip-agent-Nexus]
+    role: orchestrator
+    priority: 10
+    inherits: null
+    capabilities: [dag-orchestration, lifecycle-governance]
+    execution_eligibility: []
+    tools: [zaip-cli]
+    skills: [zaip-skill-execution]
+    write_scopes: []
+    permissions:
+      filesystem: { allow: [], deny: [workspace-write] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [zaip-cli], deny: [destructive] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [tool-use, structured-output]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 24, soft_input_tokens: 120000, max_repair_cycles: 2 }
+    contract:
+      inputs: [prepared-plan, active-work]
+      outputs: [delegation, execution-state]
+      evidence: [run-attribution]
+    review: { can_approve: false, cannot_review_roles: [orchestrator, builder] }
+    escalation: [agent-auditor]
+  - id: agent-builder
+    version: 1
+    purpose: Implement bounded TypeScript work inside declared scopes.
+    codex_name: zaip-agent-builder
+    nickname_candidates: [zaip-agent-Forge, zaip-agent-Maker, zaip-agent-Builder]
+    role: builder
+    priority: 20
+    inherits: null
+    capabilities: [typescript-delivery, test-authoring]
+    execution_eligibility: [delivery]
+    tools: [apply-patch, shell-read, test-runner]
+    skills: [zaip-skill-change]
+    write_scopes: [packages/*]
+    permissions:
+      filesystem: { allow: [declared-write-scope], deny: [outside-workspace] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [tests, typecheck, build], deny: [destructive, deploy] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [code, tool-use]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 40, soft_input_tokens: 180000, max_repair_cycles: 3 }
+    contract:
+      inputs: [task, requirements, context-pack]
+      outputs: [diff, test-results]
+      evidence: [acceptance-evidence]
+    review: { can_approve: false, cannot_review_roles: [builder] }
+    escalation: [agent-orchestrator]
+  - id: agent-task-executor
+    version: 1
+    purpose: Execute one bounded standalone Task end to end and return structured results to the orchestrator.
+    codex_name: zaip-agent-task-executor
+    nickname_candidates: [zaip-agent-Tasker, zaip-agent-Runner, zaip-agent-Executor]
+    role: task-executor
+    priority: 20
+    inherits: null
+    capabilities: [task-delivery, verification, evidence-production]
+    execution_eligibility: [delivery]
+    tools: [apply-patch, shell-read, test-runner]
+    skills: [zaip-skill-change]
+    write_scopes: [declared-write-scope]
+    permissions:
+      filesystem: { allow: [declared-write-scope], deny: [outside-workspace] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [tests, typecheck, build], deny: [destructive, deploy] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [tool-use, structured-output]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 32, soft_input_tokens: 160000, max_repair_cycles: 2 }
+    contract:
+      inputs: [task, requirements, context-pack]
+      outputs: [diff, verification, structured-outcome]
+      evidence: [acceptance-evidence]
+    review: { can_approve: false, cannot_review_roles: [task-executor, builder] }
+    escalation: [agent-orchestrator]
+  - id: agent-analyst
+    version: 1
+    purpose: Analyze interaction turns without manufacturing executable Tasks.
+    codex_name: zaip-agent-analyst
+    nickname_candidates: [zaip-agent-Analyst, zaip-agent-Insight, zaip-agent-Scout]
+    role: analyst
+    priority: 20
+    inherits: null
+    capabilities: [conversation-analysis, question-answering, repository-analysis]
+    execution_eligibility: [interaction]
+    tools: [shell-read]
+    skills: [zaip-skill-context]
+    write_scopes: []
+    permissions:
+      filesystem: { allow: [read-only], deny: [workspace-write] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [validation], deny: [mutation, deploy, destructive] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [reasoning, structured-output]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 16, soft_input_tokens: 80000, max_repair_cycles: 1 }
+    contract:
+      inputs: [interaction, context-pack]
+      outputs: [analysis, answer]
+      evidence: [run-attribution]
+    review: { can_approve: false, cannot_review_roles: [analyst] }
+    escalation: [agent-orchestrator]
+  - id: agent-execution-finalizer
+    version: 1
+    purpose: Evaluate terminal Execution evidence as the mandatory final Sub-Run for interaction or delivery and return a restricted outcome.
+    codex_name: zaip-agent-execution-finalizer
+    nickname_candidates: [zaip-agent-Finalizer, zaip-agent-Closer, zaip-agent-Settler]
+    role: execution-finalizer
+    priority: 30
+    inherits: null
+    capabilities: [lifecycle-finalization, gate-evaluation, structured-output]
+    execution_eligibility: []
+    tools: [zaip-cli, shell-read]
+    skills: [zaip-skill-execution]
+    write_scopes: []
+    permissions:
+      filesystem: { allow: [read-only], deny: [workspace-write] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [validation, zaip-cli-read], deny: [mutation, deploy, destructive] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [reasoning, structured-output]
+      preferred: [gpt-5.6-terra]
+      reasoning_effort: medium
+    budget: { soft_cycles: 8, soft_input_tokens: 40000, max_repair_cycles: 0 }
+    contract:
+      inputs: [task, descendant-results, gates, evidence]
+      outputs: [terminal-outcome, status-reason, evidence-refs]
+      evidence: [finalization-decision]
+    review: { can_approve: false, cannot_review_roles: [execution-finalizer] }
+    escalation: [agent-auditor]
+  - id: agent-reviewer
+    version: 1
+    purpose: Review changes independently and emit findings without mutating product files.
+    codex_name: zaip-agent-reviewer
+    nickname_candidates: [zaip-agent-Sentinel, zaip-agent-Lens, zaip-agent-Verifier]
+    role: reviewer
+    priority: 10
+    inherits: null
+    capabilities: [independent-review, architecture-review, security-review]
+    execution_eligibility: []
+    tools: [shell-read, test-runner]
+    skills: [zaip-skill-review]
+    write_scopes: []
+    permissions:
+      filesystem: { allow: [read-only], deny: [workspace-write] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [tests, validation], deny: [mutation, deploy] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [reasoning, tool-use]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 24, soft_input_tokens: 120000, max_repair_cycles: 0 }
+    contract:
+      inputs: [task, diff, requirements, evidence]
+      outputs: [findings, approval-state]
+      evidence: [review-report]
+    review: { can_approve: true, cannot_review_roles: [reviewer] }
+    escalation: [agent-auditor]
+  - id: agent-integrator
+    version: 1
+    purpose: Integrate reviewed worktrees and run combined gates.
+    codex_name: zaip-agent-integrator
+    nickname_candidates: [zaip-agent-Bridge, zaip-agent-Weaver, zaip-agent-Integrator]
+    role: integrator
+    priority: 10
+    inherits: null
+    capabilities: [git-integration, full-verification]
+    execution_eligibility: []
+    tools: [git, test-runner, zaip-cli]
+    skills: [zaip-skill-execution]
+    write_scopes: [integration-branch]
+    permissions:
+      filesystem: { allow: [reviewed-worktree], deny: [unreviewed-worktree] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [git-integrate, tests, build], deny: [force-push, deploy] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [tool-use, conflict-resolution]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 20, soft_input_tokens: 100000, max_repair_cycles: 1 }
+    contract:
+      inputs: [reviewed-diffs, dependency-state]
+      outputs: [integrated-diff, gate-results]
+      evidence: [integration-evidence]
+    review: { can_approve: false, cannot_review_roles: [integrator, builder] }
+    escalation: [agent-orchestrator]
+  - id: agent-auditor
+    version: 1
+    purpose: Reproduce evidence and issue the final independent audit.
+    codex_name: zaip-agent-auditor
+    nickname_candidates: [zaip-agent-Beacon, zaip-agent-Ledger, zaip-agent-Witness]
+    role: auditor
+    priority: 10
+    inherits: null
+    capabilities: [independent-review, release-audit, score-reproduction]
+    execution_eligibility: []
+    tools: [shell-read, test-runner, package-inspector]
+    skills: [zaip-skill-review]
+    write_scopes: []
+    permissions:
+      filesystem: { allow: [read-only], deny: [workspace-write] }
+      network: { allow: [], deny: [external] }
+      shell: { allow: [tests, validation, package-inspection], deny: [product-mutation, deploy] }
+      deployment: { allow: [], deny: [all] }
+    model:
+      required_capabilities: [reasoning, tool-use, structured-output]
+      preferred: [policy-selected]
+    budget: { soft_cycles: 32, soft_input_tokens: 180000, max_repair_cycles: 0 }
+    contract:
+      inputs: [rubric, evidence-manifest, release-candidate]
+      outputs: [audit-report, go-no-go]
+      evidence: [reproduced-score]
+    review: { can_approve: true, cannot_review_roles: [auditor] }
+    escalation: [agent-orchestrator]
+squads:
+  - id: squad-critical-delivery
+    version: 1
+    purpose: Deliver critical work with independent review and controlled integration.
+    members: [agent-orchestrator, agent-analyst, agent-task-executor, agent-execution-finalizer, agent-builder, agent-reviewer, agent-integrator, agent-auditor]
+    max_parallelism: 5
+    delegation:
+      - { from: agent-orchestrator, to: agent-builder, capability: typescript-delivery }
+      - { from: agent-orchestrator, to: agent-task-executor, capability: task-delivery }
+      - { from: agent-orchestrator, to: agent-analyst, capability: conversation-analysis }
+      - { from: agent-orchestrator, to: agent-execution-finalizer, capability: lifecycle-finalization }
+      - { from: agent-builder, to: agent-reviewer, capability: independent-review }
+      - { from: agent-reviewer, to: agent-integrator, capability: git-integration }
+      - { from: agent-integrator, to: agent-auditor, capability: release-audit }
+    review_policy:
+      independent: true
+      executor_roles: [analyst, builder, task-executor]
+      reviewer_roles: [reviewer, auditor]
+    escalation: [agent-auditor, agent-orchestrator]

package/templates/.zaip-aios/templates/requirements/autonomous-assurance.md

@@ -0,0 +1,63 @@
+---
+schema_version: 2
+id: REQUIREMENTS-AUTONOMOUS-ASSURANCE
+area: autonomous-assurance
+title: Garantia adaptativa e execução autônoma
+status: active
+version: 1
+source_change: null
+source_release: "1.0.0"
+---
+
+# Garantia adaptativa e execução autônoma
+
+## REQ-ASSURE-001 — Garantia proporcional para Tasks standalone
+
+Uma Task avulsa deve provar todos os Acceptance Criteria com profundidade proporcional ao risco, sem criar validação cerimonial.
+
+- `AC-ASSURE-001-01`: risco `lite` exige exatamente uma validação tipada aprovada e uma Evidence tipada aprovada; ambas podem cobrir vários ACs, mas a união precisa cobrir todos os ACs da Task.
+- `AC-ASSURE-001-02`: risco `standard` exige exatamente duas validações e duas Evidences no perfil base ou exatamente três de cada no perfil elevado; os artefatos usam modalidades distintas e incluem teste executado.
+- `AC-ASSURE-001-03`: `standard_depth: auto` seleciona o perfil elevado quando a Task possui mais de um write scope; `base` e `elevated` permitem configuração explícita.
+- `AC-ASSURE-001-04`: risco `critical` exige no mínimo três validações, Evidence dedicada por AC, teste, quality review independente, discriminação por mutação, rollback comprovado e artefatos frescos no commit final.
+- `AC-ASSURE-001-05`: uma Task sensível a segurança, migração, irreversibilidade ou múltiplos domínios não pode usar `lite` para contornar controles críticos.
+
+## REQ-ASSURE-002 — Garantia parental para SPEC e PRD
+
+Entregar uma SPEC ou PRD deve exigir prova no nível do produto planejado, além da soma dos testes das Tasks descendentes.
+
+- `AC-ASSURE-002-01`: SPEC e PRD exigem matriz completa de ACs, pelo menos três validações parentais e pelo menos três Evidences parentais aprovadas.
+- `AC-ASSURE-002-02`: SPEC exige integração, spec review e quality review; PRD exige cross-SPEC E2E, spec review e quality review.
+- `AC-ASSURE-002-03`: a revisão parental é feita por verificador diferente do autor e por Run diferente.
+- `AC-ASSURE-002-04`: todas as validações e Evidences parentais referenciam o commit final esperado; artefato de commit anterior não prova a entrega atual.
+- `AC-ASSURE-002-05`: PRD exige Evidence para cada outcome declarado, e descendants aprovados não substituem Evidence de integração ou outcome no nível parental.
+
+## REQ-AUTO-001 — Runtime autônomo opt-in e seguro
+
+O framework deve preservar execução manual como padrão e permitir autonomia somente por configuração explícita.
+
+- `AC-AUTO-001-01`: ausência de `execution` ou `execution.runtime: manual` materializa o trabalho sem invocar provider; `autonomous` exige provider, modelo, lease e paralelismo limitados.
+- `AC-AUTO-001-02`: o paralelismo efetivo é o menor limite entre projeto, plano, provider e squad; locks de DAG e write scopes continuam soberanos.
+- `AC-AUTO-001-03`: cada Task autônoma executa em Git worktree registrada, parte de raiz limpa, produz commit final, altera somente write scopes autorizados e aborta merge conflitante sem deixar merge parcial.
+- `AC-AUTO-001-04`: processos usam command allowlist, `shell: false`, diretório validado, ambiente mínimo allowlisted, limite de linha/stderr, timeout, cancelamento e budget de ferramentas/output.
+- `AC-AUTO-001-05`: checkpoints opacos de Codex ou Claude ficam somente em `.zaip-aios/local-data`, são retomáveis e removidos ao terminar; estado governado usa compare-and-swap.
+- `AC-AUTO-001-06`: Tasks `lite` têm uma tentativa; `standard` e `critical` têm no máximo três tentativas de desenvolvimento/reparo, sem loops ilimitados.
+- `AC-AUTO-001-07`: trabalho `critical` usa contexto fresco por Task e verificador independente; SPEC/PRD também exigem verificador independente mesmo quando suas Tasks são `lite`.
+
+## REQ-EVOL-001 — Delta, lições e maturidade derivada
+
+Aprendizado e alegações de maturidade devem ser derivados de fatos verificáveis do candidato atual.
+
+- `AC-EVOL-001-01`: rework recebe delta explícito de AC, write scopes, findings e baseline; contexto antigo não é copiado sem relevância observável.
+- `AC-EVOL-001-02`: lesson exige finding e locator verificável; opinião isolada não promove Rule, Requirement ou skill.
+- `AC-EVOL-001-03`: maturidade progride sequencialmente por `declared`, `implemented`, `locally_evidenced`, `cleanroom_validated`, `representative_validated` e `production_observed`.
+- `AC-EVOL-001-04`: Evidence de validação referencia o hash exato do candidato; cleanroom e estados posteriores exigem verificador independente, e produção exige Run observado.
+
+## REQ-QUALITY-001 — Gates de release e cobertura sem regressão
+
+O release deve falhar de modo discriminante quando código, distribuição ou evidência não atingirem o contrato publicado.
+
+- `AC-QUALITY-001-01`: release crítico inclui unit, E2E, arquitetura, CQRS, módulos, profile, segurança e testes negativos.
+- `AC-QUALITY-001-02`: cobertura usa baseline versionada e ratchet `max(piso, baseline anterior)` com pisos de 80% para lines/functions/statements e 75% para branches.
+- `AC-QUALITY-001-03`: baseline observada abaixo do piso pode ser registrada para transparência, mas não reduz o gate nem torna a release aprovada.
+- `AC-QUALITY-001-04`: release verifica paridade entre fonte canônica, template público e artefato distribuído, além de smoke/cleanroom sobre o candidato exato.
+

package/templates/.zaip-aios/templates/requirements/context-engine.md

@@ -0,0 +1,44 @@
+---
+schema_version: 2
+id: REQUIREMENTS-CONTEXT-ENGINE
+area: context-engine
+title: Contexto mínimo, seguro e navegável
+status: active
+version: 8
+source_change: null
+source_release: "1.0.0"
+---
+
+# Context engine
+
+## REQ-CONTEXT-001 — Seleção mínima
+
+Agentes devem construir contexto começando por configuração, Rule central, artefato ativo e Requirements referenciados, ampliando somente por relações explícitas.
+
+- `AC-CONTEXT-001-01`: o conjunto inicial não depende de artefatos globais legados.
+- `AC-CONTEXT-001-02`: eventos brutos de Run ficam fora do contexto padrão.
+- `AC-CONTEXT-001-03`: arquivos selecionados possuem motivo e budget declarado.
+- `AC-CONTEXT-001-04`: segredos, instruções não confiáveis e paths quebrados são bloqueados.
+- `AC-CONTEXT-001-05`: quando um artefato lifecycle é selecionado por ID, todos os Requirements e ACs declarados nele entram no conjunto obrigatório antes da busca lexical; o pack falha se o budget os omitir.
+
+## REQ-CONTEXT-002 — Ownership e namespaces de Rules
+
+Rules do framework e Rules específicas do projeto devem permanecer separadas, navegáveis e sem sobrescrita implícita.
+
+- `AC-CONTEXT-002-01`: Rules fornecidas pelo ZAIP existem somente em `.agents/rules/zaip/`, são registradas no `framework.lock.yaml` e nenhum arquivo de Rule existe diretamente em `.agents/rules/`.
+- `AC-CONTEXT-002-02`: Rules específicas existem somente em `.agents/rules/project/`, são preservadas por setup/upgrade e não entram no lock nem nos templates ou releases públicos.
+- `AC-CONTEXT-002-03`: setup, doctor, migração e context rejeitam ownership inválido e IDs duplicados; upgrades relocam Rules planas intactas e bloqueiam divergências antes de escrever.
+
+## REQ-CONTEXT-003 — Navegação escalável
+
+Coleções de trabalho devem ser navegadas por projeções locais descartáveis antes da leitura pontual do conteúdo Git-native.
+
+- `AC-CONTEXT-003-01`: listagens aceitam status, período, relação, limite e continuação estável, com limite padrão de 20 e máximo de 200 por página.
+- `AC-CONTEXT-003-02`: listagens de PRD, SPEC e Task omitem o PreparedPlan completo e retornam somente resumo de preparação.
+- `AC-CONTEXT-003-03`: corpos e eventos JSONL são lidos somente após selecionar IDs específicos.
+- `AC-CONTEXT-003-04`: operações comuns nunca varrem `.agents/records` ou `.agents/data`; rebuild completo exige comando e confirmação explícitos.
+- `AC-CONTEXT-003-05`: `.agents/projections/runtime` é local, ignorado pelo Git, incremental e reconstruível a partir dos records canônicos.
+- `AC-CONTEXT-003-06`: `.agents/data` e partições diárias anteriores são fallback legado somente leitura; novas escritas usam `.agents/records/<kind>/<ano>/<mês>`.
+- `AC-CONTEXT-003-07`: `context build` descobre paths e relações antes de ler conteúdo; inventário integral exige comando explícito.
+- `AC-CONTEXT-003-08`: uma consulta com ID lifecycle explícito não incorpora outros itens de `active-work`; fallback de path aceita somente o arquivo V3 canônico existente sem varrer records.
+- `AC-CONTEXT-003-09`: múltiplas entidades de uma mutação são anexadas em lote e atualizam snapshot uma única vez; reconciliação pontual recebe ID explícito e não executa full scan.

package/templates/.zaip-aios/templates/requirements/cost-observability.md

@@ -0,0 +1,39 @@
+---
+schema_version: 2
+id: REQUIREMENTS-COST-OBSERVABILITY
+area: cost-observability
+title: Tokens, custos e cobertura
+status: active
+version: 9
+source_change: null
+source_release: "1.0.0"
+---
+
+# Cost observability
+
+## REQ-COST-001 — Custo por nível e fase
+
+O sistema deve agregar tokens e custo por Task, SPEC e PRD, separados em Conversation, Planning e Execution, além de total e cobertura.
+
+- `AC-COST-001-01`: Task, SPEC e PRD expõem tokens e custo por fase e total.
+- `AC-COST-001-02`: valores indisponíveis permanecem nulos e não aparecem como zero.
+- `AC-COST-001-03`: dashboard, Kanban e Cost Monitor usam a mesma agregação sem dupla contagem.
+- `AC-COST-001-04`: métricas distinguem trabalho `new` e `rework`.
+- `AC-COST-001-05`: pergunta somente leitura possui Run com fase e entrypoint `conversation`, `task_id: null` e custo atribuível ao agregado de Conversation/projeto, sem Task artificial; uma tentativa explícita de executar usa Run de Execution mesmo quando não produz `changed_files`.
+
+## REQ-COST-002 — Consulta operacional escalável
+
+Runs devem poder ser localizadas e agregadas sem carregar seus eventos completos na resposta textual.
+
+- `AC-COST-002-01`: `zaip run list` oferece filtros por fase, entrypoint, tipo de trabalho e relações, com paginação compacta.
+- `AC-COST-002-02`: `zaip run aggregate` calcula tokens, custos e cobertura no escopo filtrado sem dupla contagem.
+- `AC-COST-002-03`: ausência de diff não reclassifica uma tentativa de execução como Conversation; o resultado e os arquivos alterados permanecem dimensões separadas.
+- `AC-COST-002-04`: cada métrica agregada expõe `known_sum`, quantidade desconhecida, completude e razão de cobertura, sem converter ausência em zero.
+- `AC-COST-002-05`: dashboard e CLI consultam snapshot incremental; JSONL canônico só é aberto para um Run explícito.
+- `AC-COST-002-06`: um único snapshot mantém contagens e somas diária, mensal e anual sem arquivos por período; records canônicos V3 são particionados fisicamente apenas por ano e mês, sem pasta diária.
+- `AC-COST-002-07`: decisões entram na mesma projeção incremental e preservam contagens por origem.
+- `AC-COST-002-08`: eventos de uso podem registrar timestamp da fonte e contagens sanitizadas de contexto, ferramentas, arquivos e trechos sem armazenar prompts.
+- `AC-COST-002-09`: Runs novos persistem um cabeçalho completo seguido de deltas compactos versionados; o parser mantém compatibilidade com JSONL V2 legado.
+- `AC-COST-002-10`: agregações expõem cobertura por Run para uso, tokens e custo com quantidades conhecidas, desconhecidas e razão; ausência de eventos nunca implica cobertura completa quando existem Runs no escopo.
+- `AC-COST-002-11`: snapshot expõe `source_latest_at` e `lag_ms` calculados a partir das entidades projetadas, sem usar horário de consulta como horário da fonte.
+- `AC-COST-002-12`: fechamento de Run sem medição persiste um evento de uso explicitamente indisponível; `context build --run` registra o tamanho estimado do pack sem armazenar prompts, e respostas resumidas omitem árvores internas disponíveis em `--view full`.