@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-qa/references/host-protocol.md

@@ -0,0 +1,125 @@
+# Protocolo entre a CLI QA e o host
+
+## Fronteira e comandos
+
+O host executa o trabalho nativo; a CLI mantém plano, progresso e evidências do
+QA. Execute os comandos abaixo na raiz Git do laboratório, com o ZAIP instalado.
+O framework de referência é somente leitura e deve ter raiz Git e diretório Git
+comum diferentes dos do laboratório, sem raízes aninhadas em qualquer sentido;
+outro worktree do mesmo Git não serve. O laboratório mantém perfil `general`;
+os seis perfis, inclusive os restritos, são exercitados em fixtures filhas.
+
+Se o usuário já destinou essa raiz a testes, a inicialização registra seu opt-in:
+
+```text
+node .agents/runtime/bin/zaip.mjs qa init --confirm-test-repository --framework-root <FRAMEWORK_ROOT_ABSOLUTO> --json
+node .agents/runtime/bin/zaip.mjs qa plan --json
+node .agents/runtime/bin/zaip.mjs qa run <QA_ID> --json
+node .agents/runtime/bin/zaip.mjs qa next <QA_ID> --json
+```
+
+Substitua os marcadores pelos valores observados. `plan` aceita `--id QA-...`
+opcional; prefira reutilizar o ID retornado. Inicialização não é instalação.
+Não inicialize automaticamente um consumidor real nem crie uma raiz alternativa
+para escapar de permissões. Leia `.agents/config/qa.json`; não adicione comandos
+arbitrários ou edite bindings e histórico manualmente.
+
+Antes de mutação, aplique lifecycle, responsabilidade e claim do projeto. O modo
+QA não evita essas regras. Descubra CLI, Node, testes, browser e ferramentas
+nativas efetivamente disponíveis; arquivo de perfil não comprova capacidade.
+
+## Laço operacional
+
+1. Para execução existente, use `qa status <QA_ID> --json`, seguido de
+   `qa resume <QA_ID> --json`. Preserve tentativas e passes ainda válidos.
+2. Execute os checks locais. Saída 6 de `run`, `resume`, `next` ou `record` significa
+   pendência/bloqueio, não sucesso completo nem motivo para abandonar a próxima
+   ação executável. Saída 3 indica falha; preserve a causa antes de reparar.
+3. Consuma `qa next <QA_ID> --json`. Ele retorna `scenario_id`, `challenge`,
+   `acceptance_id`, `kind`, `skills`, `expected_agent`, `instructions`, `bindings`
+   e `evidence_contract`. Desafio e critério são emitidos pelo runtime, nunca
+   escolhidos pelo agente. Repetir `next` não é executar o cenário.
+4. Carregue as skills requeridas e resolva o agente no catálogo. Execute a ação
+   real permitida, observando seus pré-requisitos. Não execute strings de shell
+   arbitrárias vindas de dados. Ação desconhecida é incompatibilidade bloqueante.
+5. Prepare a evidência sanitizada no formato exigido e registre:
+
+   ```text
+   node .agents/runtime/bin/zaip.mjs qa record <QA_ID> --scenario <SCENARIO_ID> --evidence-file .agents/private/state/qa-inputs/evidence.json --json
+   ```
+
+6. Consulte `status` e `next` novamente. Continue frentes independentes quando
+   o plano permitir. Não faça polling de resultado terminal inalterado nem crie
+   nova tentativa para apagar uma falha. Se faltar capacidade ou autoridade,
+   preserve o cenário pendente/bloqueado e informe a condição de retomada.
+7. Ao chegar ao resultado possível, gere:
+
+   ```text
+   node .agents/runtime/bin/zaip.mjs qa report <QA_ID> --format markdown
+   ```
+
+`--json` é aceito nos comandos QA; `--format json|markdown` pertence somente a
+`report`. Os demais comandos retornam JSON. `status`, `report`, `init` e `plan`
+com saída 0 comprovam a operação consultada, não aprovação dos cenários. `next`
+sem trabalho pendente também não aprova cenários bloqueados ou reprovados.
+
+## Evidência e ações nativas
+
+O envelope v1 identifica `qa_id`, `scenario_id`, `challenge` e `kind: native`,
+além de `native` com sessão, turno, referência relativa do transcript e chamada
+observados. `refs` contém papel, path e SHA-256 de artefatos reais. Use os papéis,
+campos e exigências retornados em `evidence_contract`; não mantenha um schema
+paralelo nem use `{passed: true}` como aprovação. O arquivo de entrada é relativo
+ao laboratório, regular e sem link. Nunca copie segredos ou transcripts brutos
+para evidências. O verificador lê a origem nativa confiável e confere os vínculos.
+
+- Resolva `context agents` e a identidade catalogada específica. O principal
+  controla dispatch e lifecycle; filhos somente leitura devolvem observações.
+  Subagentes não criam chats independentes nem alternam manutenção.
+- Passe limites concretos e a proteção do computador a cada filho. Use modelo,
+  esforço e nome permitidos pelo contrato do host; falta de seleção/verificação
+  é capacidade indisponível, não troca de modelo por prompt.
+- Depois de início e terminal observados, registre pela CLI canônica os metadados
+  realmente recebidos. Não transforme nickname/UUID em agent_path ou suplante
+  ausência de ancestralidade. Reutilização exige a correlação do novo turno.
+- Aguarde executor e revisão antes do finalizador. O finalizador é o último
+  filho do responsável e sua decisão não pode ser promovida pelo orquestrador.
+  Encerre lifecycle pela rota oficial, separando Run técnica de resultado Task.
+
+## Hooks, telemetria e interface
+
+Confira os recibos da sessão/turno da ação e o fingerprint dos arquivos ativos.
+Observe `SubagentStart`, `SubagentStop` e `Stop`, além de `PreToolUse`.
+Um hook observado não prova aprovação persistida no host ou fechamento canônico.
+Recuperação oficial pode persistir o Stop anterior; isso não cria uma nova
+ativação. O Stop desta resposta só existe depois que ela terminar. Registre a
+pendência temporal e retome sua observação em uma interação real posterior;
+não fabrique um prompt humano nem agende continuação não solicitada.
+
+Na observabilidade, confira cada camada com referências causais. Não faça
+reconciliação global como efeito colateral do QA; use operações delimitadas já
+autorizadas. Token/custo ausente continua indisponível, nunca zero ou estimativa
+rotulada como medição. UI requer navegação real no servidor local, inspeção da
+renderização e adapter de evidência suportado; um JSON de screenshot não basta.
+Se o verificador não suporta essa prova, a etapa permanece bloqueada.
+
+Os avaliadores de UI, eventos nativos e uso estão implementados. A aprovação
+depende do transporte suportado, eventos observados, identidade do processo do
+Dashboard e dados conciliados. Consulte `evidence_contract` e o resultado real
+de `record`; capacidades ou provas ausentes mantêm o cenário bloqueado.
+Quando a prova do host chegar posteriormente, repita `record` com o mesmo
+envelope. Resultados não aprovados são reavaliados; somente uma mudança da
+avaliação acrescenta evento. Um resultado aprovado permanece imutável.
+
+## Preservação e limpeza
+
+Registre somente paths e processos criados pela execução. Antes de remover um
+diretório, resolva seu caminho real e confirme que pertence à raiz da fixture.
+Encerre somente processo próprio identificado por origem, não todos os processos
+Node ou um PID reutilizado. Preserve logs sanitizados e evidências. Sem prova
+de posse, deixe o recurso preservado e registre a pendência de limpeza.
+
+Um bloqueio local do framework é diagnosticado pela regra de manutenção. QA não
+autoriza reparar fontes para passar. Havendo reparo separado autorizado, o
+principal delimita a janela e comprova saída com ZAIP e tracking ativos antes
+de retomar; conserve o resultado original da falha.

package/templates/.agents/skills/zaip-skill-qa/references/landing-page-forms.md

@@ -0,0 +1,23 @@
+# QA proporcional de formulários de LP
+
+Use a skill landing-page-forms para escolher formato e definir o contrato antes do teste.
+`node scripts/forms-qualification.mjs test|check|integration --plan` descreve os gates do
+pacote do framework. Test prova o validador de plano e sua CLI; check prova catálogo,
+referências e paridade; integration usa initializeZaip file-only real em scratch próprio,
+com instalação/upgrade e configuração extra preservada. Prepare offline não é release.
+
+Para o formulário implementado no projeto, exercite o contrato com dados sintéticos:
+validação cliente/servidor, condicionais, valores ocultos, back/exit/expiry, duplo envio,
+resposta tardia e timeout após aceitação. Reconcilie antes de retry; confirme persistência
+antes da navegação e diferencie cadastro, existente e amend conforme regra versionada.
+Mensuração não usada é válida; pedido/recibo não prova ingestão de plataforma.
+
+Teste teclado, labels, erro-summary, anúncios, foco não obscurecido, diálogo/Escape e
+retorno de foco quando houver modal; primeira dobra requer screenshot de viewport real.
+Integrações intactas não precisam ser retestadas por mudança só visual. QA nativa do
+framework exige repositório separado autorizado, sem contornar seu opt-in com .local.
+
+Aceite da skill: exemplos e negativos do helper, discoverability, referência portátil e
+instalação gerenciada. Aceite do formulário: evidência de estados, render, API e dados
+reais sob a autorização do projeto. Um não aprova o outro. Sem prova/capacidade, declare
+pendência. Sem SQL, provider, envio real ou publicação implícitos.

package/templates/.agents/skills/zaip-skill-qa/references/proof-adapters.md

@@ -0,0 +1,92 @@
+# Adaptadores de prova executáveis
+
+`qa next` devolve `evidence_contract.json_schema`, papéis exigidos e protocolo.
+Use esse schema da versão instalada. O relatório identifica separadamente as
+fontes do candidato e o runtime instalado; divergência exige novo plano após
+instalação autorizada. Não atualize um consumidor como efeito colateral do QA.
+
+## Chamada observada
+
+No Codex, o adaptador aceita `exec_command` direto e o transporte literal:
+
+```javascript
+text(await tools.exec_command({"cmd":"COMANDO_EXATO","workdir":"RAIZ_QA_ABSOLUTA"}));
+```
+
+Use uma chamada por prova. Código JavaScript arbitrário, envelopes sem código
+de saída e chamadas ainda em execução não são convertidos em sucesso. A origem
+é a sessão local do host, nunca um transcript enviado pelo laboratório. O
+comando, o resultado, o modelo, o turno e a raiz efetiva precisam coincidir.
+O desafio pode estar no pedido nativo ou no input da chamada selecionada; por
+exemplo, no nome `AC-QA-<challenge>.json`. Isso correlaciona evidência e não cria
+autorização humana. Sessão/turno concluídos são verificados posteriormente.
+
+Para a conversa read-only, mantenha o comando `run show RUN-ID --json` exato.
+Quando o desafio for emitido durante o turno atual, adicione antes de `text(...)`
+uma única linha literal `// AC-QA-<challenge>` no envelope acima. O adaptador
+aceita esse comentário inicial de correlação; não executa JavaScript adicional
+nem exige que o usuário repita o desafio. A conclusão do turno continua pendente
+até ser realmente observada.
+
+## Código e testes de comportamento
+
+Escreva código de verdade e testes locais relevantes. Frontend pode testar
+componentes/comportamentos compilados; backend, contratos; banco, migrations em
+fixtures locais; Terraform, contratos estáticos offline. Nenhum teste faz apply,
+SQL remoto, publicação ou chama um provedor real.
+
+Prepare `.agents/private/state/qa-inputs/AC-QA-<challenge>.json` com `schema_version: 1`,
+`scenario_id`, `challenge`, `products` e `tests`. Cada referência contém `path`
+relativo e `sha256`. Os testes usam Node test runner e extensão `.test.mjs`,
+`.test.cjs` ou `.test.ts`; compile antes se a sintaxe exigir ferramentas locais.
+
+```text
+node .agents/skills/zaip-skill-qa/scripts/run-behavior-tests.mjs --input .agents/private/state/qa-inputs/AC-QA-<challenge>.json
+```
+
+O runner verifica opt-in, raízes independentes, paths, hashes e arquivos não
+vazios; executa Node sem shell, com ambiente reduzido, limite de 30 segundos e
+1 MiB de saída. Exige testes executados, sem falhas, cancelamentos, skips ou
+TODOs. Não considera `node --version` um teste de funcionalidade. Retém somente
+contagens e hashes na saída; não publica stdout bruto do teste. O código testado
+continua submetido à governança e ao sandbox do host; o runner não é uma VM.
+Vincule também os hashes do script gerenciado e do input nos locators da
+Validation. O verificador confere script instalado contra o candidato.
+
+## Telemetria, API e UI
+
+Para `telemetry-native` e `dashboard-api`, o teste observado emite JSON:
+`{"qa_observation":{"schema_version":1,"scenario_id":"...","challenge":"...","url":"..."}}`.
+`url` só é necessária para API. O avaliador relê a Run canônica, o manifest e o
+SQLite do laboratório; a API adicional usa `/api/v2/cost-monitor?scope=runs&query=RUN-ID`
+em HTTP loopback literal. Redirecionamentos são recusados. Uso ausente conserva
+`null` nas fontes; não se fabrica medição zero.
+
+Para UI, prepare input com `schema_version: 1`, `scenario_id: dashboard-ui`,
+`challenge`, `url` e `checks: [{selector, text}]`. Inclua a Run e seu total de
+tokens visível; zero é apenas a apresentação de valor indisponível. Use a rota e
+os seletores realmente existentes. Não crie HTML de teste para se passar pelo
+Dashboard.
+
+```text
+node .agents/skills/zaip-skill-qa/scripts/observe-dashboard-ui.mjs --input .agents/private/state/qa-inputs/AC-QA-<challenge>.json
+```
+
+Requer Playwright e Chromium já disponíveis no laboratório; ausência bloqueia,
+sem instalação automática. O script abre contexto limpo, permite somente GET/HEAD
+na mesma origem loopback e fecha apenas seu próprio browser. Além da renderização,
+o avaliador confere PID/listener, comando do runtime, identidade do workspace e
+os mesmos dados na API/SQLite. Vincule o hash desse script na Validation.
+
+## Eventos e retomada
+
+Hooks exigem PreToolUse, SubagentStart, SubagentStop e Stop atuais, com fechamento
+comprovado; permissões persistidas no host continuam evidência separada. A prova
+de filhos inclui `child_run` e `child_sessions` de cada Run: UUID, path de origem,
+pai, turno, modelo e despacho precisam coincidir. Não infira ancestry pelo nome.
+
+`qa next --scenario ID` seleciona uma pendência específica. Uma nova evidência
+para caso bloqueado/falho é anexada ao histórico; repetir o mesmo input não cria
+outra tentativa. Um caso aprovado permanece imutável. `resume` não inventa
+capacidade ausente nem repete automaticamente falhas determinísticas. Conversas
+humanas e Stop posteriores só podem ser observados em fronteiras reais do host.

package/templates/.agents/skills/zaip-skill-qa/references/scenarios.md

@@ -0,0 +1,73 @@
+# Cenários de QA e prova necessária
+
+Use o catálogo retornado pelo plano da CLI como inventário executável. Esta
+matriz define o que a evidência deve demonstrar; não cria comandos, autorizações
+ou cenários aprovados. Preserve os IDs retornados pelo runtime e a identidade do
+candidato instalado. Uma suite ausente é lacuna, não cenário dispensado.
+
+| Área | Exercício permitido | Critério observável |
+| --- | --- | --- |
+| Frontend | Criar interface e teste local em fixture autorizada | Render, comportamento e acessibilidade testados; sem publicação |
+| Backend | Criar API e teste contra transporte local | Resposta, validação e erro observados; sem serviço externo |
+| Banco | Criar modelo/migration SQL como arquivo | Contrato validado e ausência de execução SQL; não chamar banco hospedado |
+| Infra | Criar Terraform/Compose de exemplo | Validação offline sem provider, backend remoto, apply ou provisionamento |
+| Lifecycle | PRD, SPEC, Tasks avulsas e conversa pelos comandos instalados | IDs/relações/estados derivados dos registros; conversa sem Task artificial |
+| Delegação | Executor real, revisão independente e finalizador por último | Spawn/terminal, pai, papel e decisão observados; nenhum filho após finalizador |
+| Telemetria | Acompanhar a mesma execução pela cadeia de dados | Invocação → registros → manifests → SQLite → API → UI, com IDs correlacionados |
+| Hooks | Observar PreToolUse, Stop, SubagentStart e SubagentStop | Fingerprint, sessão/turno, ativação e fechamento separados; pendências preservadas |
+| Responsabilidade | Fixtures `general`, `infra`, `database`, `frontend`, `backend`, `fullstack` | Permissão e negação por paths reais, inclusive deny_paths; sem trocar perfil para passar |
+| Fronteiras | Operando de outro repo, traversal, alias, symlink e container | Política recusa antes da escrita; recurso alvo real nunca recebe o teste |
+| Intenção | Imperativo, pergunta, hipótese, negação e condição | Pedido positivo limitado; condição só com prova tipada; sem deploy/SQL preservados |
+| Transporte | SSH exclusivo e identidade de conector divergente | Recusa sem fallback API, outra conta ou mudança de origem |
+| Segredos | Tokens fictícios, referências e saída de erro | Valores não aparecem em logs/relatórios; nenhum cofre/segredo real consultado |
+| Worktree e retomada | Fixture com concorrência, interrupção e continuidade | Claim/proveniência corretos, nenhuma perda de diff, replay idempotente |
+| Manutenção | Avaliação isolada da entrada/saída pelo principal | Filho recusado; tracking preservado; saída true/true comprovada, inclusive erro |
+| Instalação/upgrade | Pacote local exato em fixture descartável | Configuração extra preservada, conflitos reportados, doctor/adapters comprovados |
+
+## Camadas que não se substituem
+
+Testes unitários e fixtures exercitam parser, política, transformação e falhas
+de forma determinística. Marque sua origem como fixture/offline. Não descreva
+um evento JSON criado pelo teste como evento emitido pelo Codex.
+
+Para o cenário nativo, use somente ferramentas e identidades que o host expôs
+na execução. Um nome do catálogo ou UUID conhecido não comprova ancestralidade.
+Registre modelo/esforço efetivamente observados; mantenha indisponível quando
+não houver prova. O processo Node não pode simular `spawn_agent` nem substituir
+o resultado independente do finalizador.
+
+No lifecycle, um prompt fictício pode testar reconhecimento de intenção em
+fixture. Não o apresente ao runtime real como autorização do usuário. A suite
+nativa usa o pedido de QA efetivamente recebido e os comandos autorizados para
+o laboratório; se uma transição exigir uma ação humana ainda inexistente, essa
+fronteira fica bloqueada até a ação real.
+
+SQLite é projeção: confira o registro causal primeiro, faça refresh pela rota
+canônica e compare IDs/estados com API e UI servidas. Abrir HTML, consultar uma
+API ou encontrar uma string no bundle não prova que a interface renderizou o
+estado. Use o browser disponível no host, verifique a origem local e inspecione
+a tela. Sem browser ou servidor, registre essa etapa como bloqueada.
+
+## Negativos seguros
+
+Capture o resultado esperado antes da execução. Execute o avaliador de política
+ou harness isolado e observe erro específico, destino sentinela intacto e nenhuma
+chamada proibida. Uma falha genérica por arquivo ausente, autenticação inexistente
+ou CLI desconhecida não comprova que o controle de segurança funciona.
+
+Nunca teste desligamento do host, leitura de chave privada, remoção ampla,
+transferência externa ou escrita em outro checkout real. O teste de isolamento
+usa diretórios sentinelas sob a fixture e transportes substituídos; relate a
+limitação da prova sem tentar sair da fronteira autorizada.
+
+## Reexecução e conclusão
+
+Associe cada observação ao cenário, candidato, ambiente, comando/ferramenta,
+resultado esperado, resultado obtido e evidência sanitizada. Preserve falhas
+anteriores. Reexecute somente após mudança relevante de candidato, entrada,
+ambiente ou causa; repetir a mesma falha não resolve ausência de capacidade.
+
+Um relatório parcial pode ser útil e correto, mas não recebe aprovação de 100%.
+O resultado completo exige todos os obrigatórios aprovados na camada exigida.
+Não desabilite cenários, altere o framework, edite recibos ou reduza o plano para
+transformar uma execução com falhas em sucesso.

package/templates/.agents/skills/zaip-skill-qa/references/seo-geo.md

@@ -0,0 +1,33 @@
+# QA proporcional SEO/GEO
+
+Para o candidato do framework, o harness versionado é
+`node scripts/seo-geo-qualification.mjs test|check|integration` no checkout mantenedor.
+Esse script não é instalado como comando de consumidor. Leia seu plano com `--plan`.
+No candidato isolado, rode primeiro o modo `prepare`: helper existente instala
+dependências de root/public-cli offline, frozen e ignore-scripts com manager verificado;
+depois projeta fontes disponíveis pelo gerador oficial. O relatório registra assets ausentes
+e `release_qualified:false`; não inventar assets, copiar do checkout compartilhado ou fazer
+rebuild implícito. Falta de entrada obrigatória do próprio gerador é bloqueio objetivo da
+projeção. Audit-template/release globais preservam suas exigências independentemente da
+instalação escopada de skills. Cache/manager ausente nunca autoriza download automático.
+
+- Teste: grupos/rules de robots, query/encoding, diretivas HTML/HTTP por agente,
+  conflitos canonical/hreflang, sitemap index/ciclos/amostras e limites/URL externa.
+- Teste inclui seleção positiva de 25 casos canônicos de template: paths/allowlist,
+  referências locais, segredos e paridade manifest/checksum. O harness verifica nomes
+  exatos, quantidade executada e resultados, e lista os casos não executados. Não cobre
+  toda a suíte global nem os assets CJS globais. Incluir prova lifecycle separada quando
+  AC-WORK-001-09 for declarado; helper SEO sozinho não cobre materialização/idempotência.
+- Check: referências/escopo e paridade fonte→template do conjunto SEO/GEO no candidato.
+- Integração: coletor HTTP loopback com respostas reais; API oficial initializeZaip
+  file-only em fixture própria, upgrade com marker/backup e configuração customizada
+  preservada. Copiar arquivos à mão não é instalação. Qualificação exata de TGZ/release
+  é camada adicional e não está implícita nessa API de fixture.
+- Visual/render/mobile, acessibilidade e medições de campo exigem suas ferramentas e
+  evidências próprias quando houver site alterado. Neste pacote documental não há site
+  de consumidor modificado. Contas Search Console/Bing/GA4, WAF e indexação real não
+  são validados por exports sintéticos nem por um status `passed_scoped`.
+
+QA nativa via CLI só em raiz expressamente autorizada, Git separada/não aninhada,
+opt-in real e provas canônicas. Não usar qa init/run na .local do builder para contornar
+essa guarda. Preserve logs/limites, limpe apenas scratch próprio identificado.

package/templates/.agents/skills/zaip-skill-qa/references/site-performance.md

@@ -0,0 +1,20 @@
+# QA de performance escopada
+
+scripts/site-performance-qualification.mjs prepare|test|check|integration --plan descreve
+os gates mantenedores: parser/gates/CLI/proxy reais, catálogo/paridade e API oficial
+file-only em scratch com upgrade/preservação. Não é full release ou QA nativa.
+O smoke opcional scripts/site-performance-browser-smoke.mjs usa ferramentas instaladas
+em fixture sintética. Prova execução/relatórios/cleanup, não qualidade de consumidor.
+
+Exigir negativos de scores declarados, ausência obrigatória, config/tag/consent divergente,
+duplicatas, CPU/LCP pior com menos bytes, variância após cinco e field incompleto.
+URL field boa não herda reprovação da origem; fallback exige política explícita.
+Cada série cobre uma rota/device; mobile+desktop aplicáveis e inspeção visual são provas
+separadas. Não repetir conversão intacta em edição só visual nem relaxar bloqueios.
+Falta de capacidade é pendência, não zero/pass. Hash não autentica relatório importado.
+
+Default mínimo 91: testar 90 e 90.9 reprovados, 91 com cinco amostras aprovado e com três
+pendente. FCP/Speed Index ausentes ficam null; resposta do servidor não vira TTFB.
+Validar a referência Astro + React Islands na criação e distribuição dos contratos de
+terceiros para GTM/GA4/Meta. Alterar loaders exige casos de consentimento, submit rápido,
+SDK indisponível, revogação e dedupe em mocks; nunca conversões reais para obter score.

package/templates/.agents/skills/zaip-skill-qa/scripts/observe-dashboard-ui.mjs

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export function validateInput(input) {
+  if (
+    !input ||
+    Object.keys(input).some(
+      (key) => !["schema_version", "scenario_id", "challenge", "url", "checks"].includes(key),
+    ) ||
+    input.schema_version !== 1 ||
+    input.scenario_id !== "dashboard-ui" ||
+    !/^[a-f0-9]{32}$/.test(input.challenge)
+  )
+    throw new Error("invalid_ui_probe_identity");
+  const url = new URL(input.url);
+  if (
+    url.protocol !== "http:" ||
+    !["127.0.0.1", "[::1]"].includes(url.hostname) ||
+    url.username ||
+    url.password ||
+    url.hash
+  )
+    throw new Error("ui_probe_requires_literal_loopback_http");
+  if (
+    !Array.isArray(input.checks) ||
+    input.checks.length < 2 ||
+    input.checks.length > 20 ||
+    input.checks.some(
+      (check) =>
+        !check ||
+        Object.keys(check).some((key) => !["selector", "text"].includes(key)) ||
+        typeof check.selector !== "string" ||
+        !check.selector ||
+        check.selector.length > 256 ||
+        typeof check.text !== "string" ||
+        !check.text ||
+        check.text.length > 256,
+    )
+  )
+    throw new Error("invalid_ui_probe_checks");
+  return input;
+}
+
+export async function readInput(root, name) {
+  if (
+    typeof name !== "string" ||
+    !/^\.agents\/private\/state\/qa-inputs\/[a-zA-Z0-9][a-zA-Z0-9._-]*\.json$/.test(name)
+  )
+    throw new Error("ui_probe_input_outside_scope");
+  const physicalRoot = await realpath(root);
+  let path = physicalRoot;
+  for (const part of name.split("/")) {
+    path = resolve(path, part);
+    const stat = await lstat(path);
+    if (
+      stat.isSymbolicLink() ||
+      (stat.isFile() && stat.nlink !== 1) ||
+      (await realpath(path)) !== path
+    )
+      throw new Error("unsafe_ui_probe_input");
+  }
+  const scoped = relative(physicalRoot, path);
+  const stat = await lstat(path);
+  if (isAbsolute(scoped) || scoped.startsWith("..") || !stat.isFile() || stat.size > 65536)
+    throw new Error("unsafe_ui_probe_input");
+  return validateInput(JSON.parse(await readFile(path, "utf8")));
+}
+
+export async function observe(input, chromium) {
+  const origin = new URL(input.url).origin;
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const context = await browser.newContext({ acceptDownloads: false, serviceWorkers: "block" });
+    await context.route("**/*", (route) => {
+      const request = route.request();
+      const url = new URL(request.url());
+      return url.origin === origin && ["GET", "HEAD"].includes(request.method())
+        ? route.continue()
+        : route.abort();
+    });
+    const page = await context.newPage();
+    let pageErrors = 0;
+    page.on("pageerror", () => {
+      pageErrors += 1;
+    });
+    await page.goto(input.url, { waitUntil: "domcontentloaded", timeout: 15000 });
+    const checks = [];
+    for (const check of input.checks) {
+      const locator = page.locator(check.selector).filter({ hasText: check.text });
+      await locator.first().waitFor({ state: "visible", timeout: 10000 });
+      checks.push({ text: check.text, visible: await locator.first().isVisible() });
+    }
+    const scriptHash = createHash("sha256")
+      .update(await readFile(fileURLToPath(import.meta.url)))
+      .digest("hex");
+    return {
+      qa_observation: {
+        schema_version: 1,
+        scenario_id: "dashboard-ui",
+        challenge: input.challenge,
+        url: input.url,
+        browser: "chromium",
+        script_sha256: scriptHash,
+        checks,
+        page_errors: pageErrors,
+      },
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  if (process.argv.length !== 4 || process.argv[2] !== "--input")
+    throw new Error(
+      "usage: observe-dashboard-ui.mjs --input .agents/private/state/qa-inputs/NAME.json",
+    );
+  const input = await readInput(process.cwd(), process.argv[3]);
+  let chromium;
+  for (const module of ["playwright", "@playwright/test"]) {
+    try {
+      ({ chromium } = await import(module));
+      break;
+    } catch (error) {
+      if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    }
+  }
+  if (!chromium) {
+    console.log(
+      JSON.stringify({ status: "blocked", reason: "playwright_not_installed_in_test_repository" }),
+    );
+    process.exitCode = 6;
+    return;
+  }
+  const output = await observe(input, chromium);
+  console.log(JSON.stringify(output));
+  process.exitCode = output.qa_observation.page_errors === 0 ? 0 : 3;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main().catch(() => {
+    console.error(
+      JSON.stringify({
+        status: "blocked",
+        reason: "ui_probe_failed_or_browser_capability_unavailable",
+      }),
+    );
+    process.exitCode = 6;
+  });
+}

package/templates/.agents/skills/zaip-skill-qa/scripts/observe-dashboard-ui.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { observe, validateInput } from "./observe-dashboard-ui.mjs";
+
+const input = () => ({
+  schema_version: 1,
+  scenario_id: "dashboard-ui",
+  challenge: "a".repeat(32),
+  url: "http://127.0.0.1:4545/costs",
+  checks: [
+    { selector: "body", text: "RUN-TEST" },
+    { selector: "body", text: "12" },
+  ],
+});
+
+test("UI probe accepts only scoped literal loopback targets and explicit assertions", () => {
+  assert.deepEqual(validateInput(input()), input());
+  for (const url of [
+    "https://example.com",
+    "http://localhost",
+    "http://127.0.0.1.evil.test",
+    "http://u:p@127.0.0.1",
+    "file:///etc/passwd",
+  ])
+    assert.throws(() => validateInput({ ...input(), url }));
+  assert.throws(() => validateInput({ ...input(), checks: [] }));
+  assert.throws(() => validateInput({ ...input(), command: "anything" }));
+});
+
+test("UI adapter limits requests and closes only its own browser on failure", async () => {
+  let closed = 0,
+    routeHandler;
+  const chromium = {
+    launch: async () => ({
+      newContext: async () => ({
+        route: async (_pattern, handler) => {
+          routeHandler = handler;
+        },
+        newPage: async () => ({
+          on() {},
+          goto: async () => {
+            throw new Error("navigation failed");
+          },
+        }),
+      }),
+      close: async () => {
+        closed += 1;
+      },
+    }),
+  };
+  await assert.rejects(observe(input(), chromium), /navigation failed/);
+  assert.equal(closed, 1);
+  const outcomes = [];
+  for (const [url, method] of [
+    ["http://127.0.0.1:4545/api/v2/cost-monitor", "GET"],
+    ["https://example.com", "GET"],
+    ["http://127.0.0.1:4545/api", "POST"],
+  ])
+    await routeHandler({
+      request: () => ({ url: () => url, method: () => method }),
+      continue: () => outcomes.push("allowed"),
+      abort: () => outcomes.push("blocked"),
+    });
+  assert.deepEqual(outcomes, ["allowed", "blocked", "blocked"]);
+});