Specsfy 04 Validate

Validar a especificação

Preparação obrigatória

Antes de executar esta skill, carregue obrigatoriamente $specsfy-setup na raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa. Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma pendência.

Modo de interação

Modo de interação: perguntas. Antes de formular qualquer pergunta, leia e aplique o Contrato de perguntas numeradas de .specsfy/Spec.md.

Trate spec.md como a única fonte da verdade e como código em linguagem natural: verifique primeiro o formato rígido, depois clareza, completude, consistência e testabilidade semanticamente.

Orquestrar a conversa

Ao concluir esta etapa ou detectar trabalho de outra etapa, anuncie Pendência detectada: <descrição> — ação: resolvendo nesta etapa e resolva-a quando pertencer ao próprio escopo. Quando houver troca de responsabilidade, anuncie Transição automática: $specsfy-04-validate → $<destino> — motivo: <motivo> — resultado esperado: <resultado> e carregue imediatamente a skill de destino, sem pedir confirmação nem repetir o comando. Continue na mesma conversa. Depois de uma correção necessária a esta etapa, anuncie Retomada automática: $<destino> → $specsfy-04-validate — pendência resolvida: <resultado> e retome-a imediatamente. Reavalie o estado após cada handoff para evitar ciclos. Não peça confirmação para o handoff; ações sensíveis continuam exigindo autorização específica.

Executar a validação

1. Resolva specs/<estado>/<NNNN>-<slug>/spec.md pelo caminho informado; se houver várias specs e nenhum slug, pergunte qual validar.
2. Confirme Formato: Specsfy/2.0, os três atos na ordem, slug igual ao diretório e pacote restrito a spec.md e ao diretório opcional research/.
3. Para toda API ou documentação externa consultada, confirme uma evidência local em research/ e seu índice em Artefatos de pesquisa armazenados; esse material é informativo, nunca uma segunda fonte normativa.
4. Enquanto Status ou Definition Gate ainda estiverem pendentes, execute:

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft

1. Leia references/quality-gates.md e faça a revisão semântica.
2. Confira o campo Interface para pessoas. Se for Sim, exija na seção 10 stack e convenções observadas, telas e responsabilidades, fluxo de informação e navegação, menus e navegação principal, formulários e ações, composição e disposição, estados e acessibilidade. Confira se a tecnologia proposta segue as fontes da stack ou se a lacuna foi registrada para a pessoa. Um CRUD sem telas e formulário é BLOCKER; retorne automaticamente ao $specsfy-02-backlog para esclarecer a lacuna.
3. Compare research, requisitos, BDD, plano técnico, modelo de dados, contratos, TDD, matriz e tarefas. Confirme no mínimo três AC distintos para a feature inteira e para cada US, FR e NFR; não confunda “arquivo bem formatado” com “especificação correta”.
4. Quando produto, arquitetura ou segurança forem materiais, leia references/review-lenses.md, registre findings na seção 13 e execute scripts/review_findings.mjs. P1 Open mantém o gate pendente.
5. Se a definição alterar stack ou persistência, exija que a Definition of Done cite respectivamente .specsfy/STACK.md ou .specsfy/DATABASE.md. Para mudança material de finalidade ou capacidade, exija revisão de PROJECT.md; para regra nova confirmada, exija .specsfy/RULES.md.
6. No aceite final, procure tarefas [MIGRATION] e execute verify_evidence.mjs --delivery para cada uma. Mantenha o Delivery Gate pendente quando a tarefa estiver aberta ou quando o arquivo, o comando de aplicação ou a consulta de estado estiver ausente.

Classificar achados

• BLOCKER: impede tarefa ou teste correto; requisito contraditório, sem comportamento observável, decisão de alto impacto ausente ou cenário principal não coberto.
• WARNING: aumenta retrabalho ou risco, mas admite implementação segura.
• NOTE: melhoria editorial sem efeito material.

Para cada achado, cite seção ou ID, explique o impacto e proponha uma correção concreta.

Gate

Retorne exatamente um resultado:

• READY: nenhuma falha de formato e nenhum BLOCKER sem resolução.
• NOT READY: qualquer falha estrutural ou BLOCKER.

Inclua contagens, cobertura mínima US/FR/NFR ↔ 3 ACs e os três achados mais importantes e a transição automática:

• READY → $specsfy-05-tasks para planejar a seção 14;
• NOT READY → retorno a $specsfy-02-backlog quando faltar decisão; a o refinamento do backlog executa seu ciclo completo e esta validação só é retomada depois de fechar as lacunas ou registrar a saída explícita avançar; após essa saída, registre NOT READY e não reabra o mesmo ciclo nesta retomada; quando a correção já estiver decidida, use $specsfy-update-spec para uma spec anteriormente aprovada e $specsfy-03-specify para a definição inicial.

Anuncie o motivo e carregue imediatamente a skill escolhida.

Registrar no arquivo único

Sem alterar requisitos automaticamente:

1. atualize Gate do Ato I — Definição na seção 13 com resultado, data e achados;
2. em READY, defina Definition Gate: Passed e Status: Defined;
3. em NOT READY, defina Definition Gate: Failed, Plan Gate: Pending, Delivery Gate: Pending e mantenha Status: Draft;
4. execute novamente validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md sem --allow-draft quando o gate passar;
5. relate o resultado no chat.

Quando o Definition Gate passar, execute specsfy transition <id> defined. Em review, use a mesma análise para o aceite final. Com Delivery Gate passado, Status Complete e a DoD comprovada, execute specsfy transition <id> completed. Antes disso, chame $specsfy-interviewer quando uma resposta puder mudar a entrega ou o Effort.

Se o usuário pedir correções, edite as seções de origem, preserve IDs e revalide. Nunca crie outro arquivo de especificação ou validação.

Enforcement do repositório

Use o mesmo runner localmente e no CI:

node .agents/skills/specsfy-04-validate/scripts/verify_repo.mjs . \
  --boundary local --timeout-seconds 300 --max-output-bytes 65536

As fronteiras local, git e ci não mudam a política. --attestation PATH é a única forma de persistir uma atestação; --self-test executa canários em diretório temporário e nunca produz binding probatório. A atestação schema 2 liga commit, digest executável, checks aprovados, tarefas e hashes de arquivos. O digest cobre comandos, limites e os arquivos da política. Não aceite um gate que passa em apenas uma fronteira, excede limites ou trunca diagnóstico sem marcar truncated.

O contrato do catálogo exige as quatorze skills base, specsfy-setup, specsfy-documentator e as três specsfy-aux-*; também valida cada specsfy-specialist-* instalada, sem impor um total máximo de especialistas. O Gherkin BDD é referência exclusiva da spec.md: o enforcement nunca executa .feature. Ele executa os testes derivados com Pest em projetos PHP, inclusive PHP + Node. Em projeto Node sem PHP, exige um script test:tdd; quando ausente, falha orientando a skill a perguntar ao usuário e sugerir Vitest.

Especialistas sob demanda

Leia references/specialists.md quando um gate depender de revisão técnica específica. Instalação é recomendação explícita, nunca efeito colateral da validação.