@zaip-ai/cli 0.1.0 → 1.0.1

package/templates/.zaip-aios/templates/skills/zaip-skill-prd/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: zaip-skill-prd
+description: Create, refine, prepare, and analyze ZAIP PRDs that map business outcomes to SPECs and Task DAGs while preserving draft status until the user explicitly requests ready or execution.
+---
+
+# Trabalhar com PRDs
+
+PRD é opcional e permanece em Definição com `status: draft` durante criação, revisão, refinamento e `prepare`. Ter SPECs ou PreparedPlan válido não autoriza promoção.
+
+## Limite de autoridade
+
+1. Não invoque `prd ready`, `prd execute` ou `prd activate` por inferência, conveniência ou conclusão do conteúdo.
+2. Pedido para criar, revisar, aprovar conteúdo, refinar, planejar ou preparar preserva `draft`.
+3. Somente pedido explícito para mover a “Pronto para Executar” delega a promoção para `$zaip-skill-move-prd`.
+4. Somente pedido explícito para executar delega preparação necessária e execução para `$zaip-skill-execution`.
+
+## Create e refine
+
+1. Registre problema, usuários, valor, outcomes mensuráveis, restrições, hipóteses, riscos e não objetivos sem executar nada.
+2. Mantenha o PRD agnóstico de linguagem, framework, banco, infraestrutura e fornecedor. Uma tecnologia só aparece quando for restrição externa real de negócio, regulação ou compatibilidade contratual; registre-a como restrição, não como desenho da solução.
+3. Permita múltiplos PRDs pendentes; compare por valor, risco, custo e evidência, e refine somente os escolhidos.
+4. Crie uma ou mais SPECs técnicas ligadas ao PRD quando solicitado. PRD e SPECs novas continuam em `draft`; cada Change planejada deve pertencer exatamente a uma dessas SPECs.
+5. Não crie Tasks, Changes, Executions ou Runs de execução durante conversa/refinamento; telemetria de conversation/planning pode registrar o uso sem torná-lo executável.
+6. Para refine Git-native, edite somente o arquivo canônico retornado pelo create enquanto `status: draft`; preserve ID/`created_at`, incremente `revision`, atualize `updated_at` e valide com `zaip prd show <ID>`. Não use `prepare` como encerramento automático da criação. Depois de `ready`, não faça patch manual: gere nova revisão do plano antes da execução ou rework após materialização.
+
+Durante essa etapa, a Execution universal `interaction` e sua Run raiz continuam obrigatórias para telemetria e rastreabilidade; a proibição acima refere-se somente a Execution `delivery` e a Runs de execução.
+
+## Prepare
+
+1. Bloqueie PRD sem SPEC, SPEC de outro PRD, referência quebrada, AC vago, DAG cíclica ou write scopes concorrentes.
+2. Construa uma DAG global que pode atravessar SPECs e inclua integração/gates como dependências explícitas.
+3. Gere e valide o PreparedPlan conforme [o contrato compacto](../zaip-skill-execution/references/prepared-plan.md), persista-o e pré-aloque IDs sem materializar trabalho executável nem mudar `draft` para `ready`.
+4. Após `prepare`, mostre que o PRD continua em Definição e pare; não encadeie `prd ready` ou `prd execute` sem a solicitação explícita correspondente.
+
+## Handoff e analyze
+
+1. Pare em Definição após `prepare`. Somente após pedido explícito de promoção, use `$zaip-skill-move-prd`; somente após pedido explícito de execução, delegue materialização, ativação e orquestração para `$zaip-skill-execution`.
+2. Na análise, mostre visão macro por PRD: SPECs, Tasks, Executions, Runs, outcomes, AC/evidência, retrabalho, tokens e custo por fase/total.
+
+## Assurance de outcomes
+
+1. Antes de entregar um PRD, construa a matriz parental completa de ACs e outcomes e produza pelo menos três validações e três Evidences próprias.
+2. As modalidades mínimas são cross-SPEC E2E, spec review e quality review por autor/Run independente, todas no commit final esperado.
+3. Cada outcome possui Evidence explícita. SPECs e Tasks aprovadas são pré-condições, não substitutos para a prova de integração e de resultado no nível do PRD.

package/templates/.zaip-aios/templates/skills/zaip-skill-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP PRD"
+  short_description: "Crie PRDs sem promover antes da autorização."
+  default_prompt: "Use $zaip-skill-prd para criar ou preparar um PRD e mantê-lo em draft até eu pedir promoção ou execução."

package/templates/.zaip-aios/templates/skills/zaip-skill-preview/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: zaip-skill-preview
+description: Discover, start, inspect, and stop local frontend or dashboard previews safely.
+---
+
+# Abrir preview local
+
+1. Identifique a superfície pedida: produto em `apps/frontend`, site público em `apps/site` ou dashboard em `.agents/dashboard`.
+2. Descubra package manager, workspace, script e variáveis pelo repositório; não assuma path pessoal, porta fixa ou comando legado.
+3. Reuse servidor saudável somente após confirmar processo, workspace e superfície. Caso contrário, escolha loopback e porta livre, inicie o processo oculto e registre PID/comando.
+4. Aguarde por health polling com timeout curto; não use sleep cego.
+5. Abra a URL com o browser disponível e verifique renderização, console, rede e acessibilidade relevantes ao pedido.
+6. Mantenha frontend, site e dashboard isolados; o site não importa dashboard e o dashboard continua local/read-only.
+7. Se o usuário pediu para abrir, mantenha o servidor disponível. Encerre somente em falha, preview efêmero ou pedido `stop`, e apenas pelo PID iniciado por esta execução.
+
+Preview não autoriza deploy nem mudanças de código. Se a inspeção revelar defeito, proponha uma Task ou execute somente com pedido explícito.

package/templates/.zaip-aios/templates/skills/zaip-skill-preview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Preview"
+  short_description: "Discover and preview frontend, site, or dashboard locally."
+  default_prompt: "Use $zaip-skill-preview to discover, start, health-check, and inspect a local frontend, site, or dashboard."

package/templates/.zaip-aios/templates/skills/zaip-skill-reconcile-telemetry/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: zaip-skill-reconcile-telemetry
+description: Auditar e reparar telemetria ausente de Runs e tarefas ZAIP usando sessões locais do Codex, sem inventar tokens ou duplicar segmentos. Usar quando o dashboard mostrar dados indisponíveis, após falha de coleta, migração, projeção inconsistente ou solicitação de backfill retroativo.
+---
+
+# Reconciliar telemetria local
+
+1. Ler `.agents/config/project.yaml`, a Rule core e a skill de observabilidade.
+2. Executar o diagnóstico, sem mutação:
+   `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs`
+3. Revisar `eligible`, `ambiguous`, `unmatched` e `already_measured`. Nunca aplicar correspondências ambíguas.
+4. Para novos Runs Codex, exigir correspondência exata por `client_turn_id` com `task_started.payload.turn_id` do arquivo local. Usar ID da Run, ID da Task, Conversation ID, contenção temporal ou vizinhança temporal mútua de até dois minutos somente para Runs legados sem `client_turn_id`:
+   `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs --apply`
+   O mesmo comando pode encerrar uma Run ainda marcada como `running` somente quando existir um único segmento local concluído com o mesmo `client_turn_id`; usar o `finished_at` desse segmento como fim real, nunca o relógio atual.
+5. Reconstruir projeções com `node packages/cli/dist/index.js projection rebuild --confirm-full-scan --json`.
+6. Reexecutar o diagnóstico. Exigir `eligible: 0` e confirmar que a cobertura aumentou ou permaneceu igual.
+7. Para corrigir segmentos exatamente duplicados entre Runs sem aplicar o backfill geral, diagnosticar e revisar `duplicate_segment_groups` e `duplicate_segment_assignments`:
+   `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs --deduplicate`
+   Aplicar somente após confirmação humana explícita com `--apply --deduplicate`. O modo preserva o evento original, insere uma supersessão indisponível antes de `run.finished` e protege o Run corrigido contra o backfill geral posterior.
+8. Quando ainda houver lacunas, executar `python .agents/skills/zaip-skill-reconcile-telemetry/scripts/inspect-local-sqlite.py`. Usar SQLite apenas como índice de threads e fonte de investigação; `threads.tokens_used` e `total_usage_tokens` de logs são acumulados e não substituem input/output por Run.
+9. Somente com autorização humana explícita para aproximação, executar primeiro o diagnóstico `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs --approximate`. O score combina distância entre data/hora/minuto/segundo de criação e 35% da diferença de duração. Aplicar com `--apply --approximate`; persistir esses vínculos como `legacy_inferred`.
+
+## Normalizar identidade de agentes
+
+Quando o dashboard exibir agentes fora de `.agents/config/agents/catalog.yaml`, execute primeiro o diagnóstico:
+
+`node .agents/skills/zaip-skill-reconcile-telemetry/scripts/normalize-run-agents.mjs`
+
+Com autorização explícita para o backfill, aplique com `--apply` e reconstrua as projeções. O script preserva `codex` e agentes válidos do catálogo; identidades históricas desconhecidas são normalizadas para `codex` sem alterar tokens, custos, vínculos ou timestamps.
+
+## Garantias
+
+- Tratar cache como subconjunto de entrada e reasoning como subconjunto de saída.
+- Calcular `total = input + output`.
+- Reutilizar preços locais editáveis em `.zaip-aios/pricing/models.json` e câmbio local quando presentes.
+- Preservar eventos históricos e inserir o evento corretivo, com `supersedes_event_id`, imediatamente antes de `run.finished`, conforme a ordem canônica do Run V2.
+- Usar cada segmento local no máximo uma vez.
+- Persistir `client_thread_id` e `client_turn_id` em todo novo `run.started` criado dentro do Codex; o ID do turn é a chave canônica de reconciliação.
+- Manter indisponível quando não houver uma correspondência local exclusiva e comprovável.

package/templates/.zaip-aios/templates/skills/zaip-skill-reconcile-telemetry/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Reconciliar telemetria ZAIP"
+  short_description: "Recupera uso local ausente em Runs passadas"
+  default_prompt: "Use $zaip-skill-reconcile-telemetry para auditar e reparar telemetria local ausente com segurança."

package/templates/.zaip-aios/templates/skills/zaip-skill-reconcile-telemetry/scripts/inspect-local-sqlite.py

@@ -0,0 +1,52 @@
+import json
+import os
+import sqlite3
+
+
+def inspect(path: str) -> dict:
+    if not os.path.exists(path):
+        return {"path": path, "exists": False, "tables": []}
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    tables = []
+    for name, sql in connection.execute(
+        "select name, sql from sqlite_master where type = 'table' order by name"
+    ):
+        columns = [row[1] for row in connection.execute(f'pragma table_info("{name}")')]
+        relevant = [
+            column
+            for column in columns
+            if any(term in column.lower() for term in ("token", "cost", "usage", "thread", "session"))
+        ]
+        tables.append({"name": name, "columns": columns, "telemetry_columns": relevant, "sql": sql})
+    diagnostics = {}
+    if any(table[0] == "logs" for table in connection.execute("select name from sqlite_master where type = 'table'")):
+        diagnostics["token_log_rows"] = connection.execute(
+            "select count(*) from logs where feedback_log_body like '%token_count%' or feedback_log_body like '%tokens_used%'"
+        ).fetchone()[0]
+        diagnostics["token_log_samples"] = connection.execute(
+            "select thread_id, substr(feedback_log_body, 1, 500) from logs where feedback_log_body like '%token_count%' limit 3"
+        ).fetchall()
+    if any(table[0] == "threads" for table in connection.execute("select name from sqlite_master where type = 'table'")):
+        diagnostics["workspace_threads"] = connection.execute(
+            "select count(*) from threads where lower(replace(cwd, '\\', '/')) = lower(replace(?, '\\', '/'))",
+            (os.getcwd(),),
+        ).fetchone()[0]
+        diagnostics["workspace_thread_tokens"] = connection.execute(
+            "select coalesce(sum(tokens_used), 0) from threads where lower(replace(cwd, '\\', '/')) = lower(replace(?, '\\', '/'))",
+            (os.getcwd(),),
+        ).fetchone()[0]
+        diagnostics["zaip_thread_samples"] = connection.execute(
+            "select id, cwd, tokens_used, rollout_path from threads where lower(cwd) like '%zaip-aios%' order by updated_at desc limit 5"
+        ).fetchall()
+    connection.close()
+    return {"path": path, "exists": True, "tables": tables, "diagnostics": diagnostics}
+
+
+root = os.path.expanduser("~/.codex")
+print(
+    json.dumps(
+        [inspect(os.path.join(root, name)) for name in ("logs_2.sqlite", "state_5.sqlite")],
+        ensure_ascii=False,
+        indent=2,
+    )
+)

package/templates/.zaip-aios/templates/skills/zaip-skill-reconcile-telemetry/scripts/normalize-run-agents.mjs

@@ -0,0 +1,63 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const apply = process.argv.includes("--apply");
+const runsRoot = join(process.cwd(), ".agents", "records", "runs");
+const catalogPath = join(process.cwd(), ".agents", "config", "agents", "catalog.yaml");
+const catalog = await readFile(catalogPath, "utf8");
+const agentsSection = catalog.split(/^squads:\s*$/m, 1)[0];
+const allowed = new Set([
+  "codex",
+  ...[...agentsSection.matchAll(/^\s*-\s+id:\s*([^\s#]+)\s*$/gm)].map((match) => match[1]),
+]);
+const files = await jsonlFiles(runsRoot);
+const replacements = new Map();
+let changedFiles = 0;
+let changedEvents = 0;
+
+for (const file of files) {
+  const source = await readFile(file, "utf8");
+  const trailingNewline = source.endsWith("\n");
+  const lines = source.split(/\r?\n/).filter((line) => line.length > 0);
+  let changed = false;
+  const normalized = lines.map((line) => {
+    const event = JSON.parse(line);
+    if (typeof event.agent !== "string" || allowed.has(event.agent)) return line;
+    replacements.set(event.agent, (replacements.get(event.agent) ?? 0) + 1);
+    event.agent = "codex";
+    changed = true;
+    changedEvents += 1;
+    return JSON.stringify(event);
+  });
+  if (!changed) continue;
+  changedFiles += 1;
+  if (apply)
+    await writeFile(file, `${normalized.join("\n")}${trailingNewline ? "\n" : ""}`, "utf8");
+}
+
+console.log(
+  JSON.stringify(
+    {
+      mode: apply ? "apply" : "diagnostic",
+      scanned_files: files.length,
+      changed_files: changedFiles,
+      changed_events: changedEvents,
+      replacements: Object.fromEntries(
+        [...replacements.entries()].sort(([a], [b]) => a.localeCompare(b)),
+      ),
+      allowed_agents: [...allowed].sort(),
+    },
+    null,
+    2,
+  ),
+);
+
+async function jsonlFiles(root) {
+  const found = [];
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) found.push(...(await jsonlFiles(path)));
+    else if (entry.isFile() && entry.name.endsWith(".jsonl")) found.push(path);
+  }
+  return found;
+}