Padrões de Qualidade

Configure os limites de prontidão e os gates por ticket que garantem qualidade nas suas especificações.

O SpecForge garante qualidade em dois pontos: o Planning Review — pontuado pelo validator contra limites de prontidão por camada antes da implementação começar — e o assay por ticket dentro do complete_work_session, que verifica o trabalho entregue de cada ticket conforme ele chega. Esta página documenta a configuração que ajusta ambos.

Padrões de qualidade são configurações no nível do projeto. Eles não são chaves do specforge configure — o comando configure aceita apenas as cinco chaves planas documentadas na referência da CLI (mcpOutputFormat, projectId, specificationId, autoSetContext, defaultProjectId). Os limites e switches de gate abaixo ficam no .specforge/config.json do projeto (config do validator + do implementation-lifecycle), semeados pelo specforge init e editáveis pelo painel.

Limites de Prontidão do Planning

O Planning Review pontua uma especificação nas suas dimensões de scoring e produz um score ponderado de 0 a 100 em cada camada do plano. Uma camada avança apenas quando seu score atinge ou excede o limite configurado. Os limites são definidos por camada, não como um único número:


{
  "thresholds": {
    "global": 80,
    "specification": 80,
    "epic": 70,
    "ticket": 70
  }
}

Opções

Camada	Tipo	Padrão	Descrição
`global`	number (0-100)	`80`	Prontidão ponderada geral de todo o plano. Quando atingida, a especificação avança para `ready`.
`specification`	number (0-100)	`80`	Prontidão mínima para os campos de nível de especificação (goals, requirements, scope, guardrails).
`epic`	number (0-100)	`70`	Piso de prontidão por épico — cada épico deve superá-lo por conta própria.
`ticket`	number (0-100)	`70`	Piso de prontidão por ticket — cada ticket deve superá-lo por conta própria.

✅ Comece com os padrões. Eles representam um equilíbrio entre rigor e velocidade. Aumente os limites conforme sua equipe ganha confiança com o fluxo de trabalho.

Proporções Estruturais

Além das dimensões pontuadas, o validator aplica proporções estruturais de topologia sobre o grafo de dependências. Elas não são proporções feature-para-teste — limitam o formato do grafo de dependências:

Opção	Tipo	Padrão	Descrição
`topology.maxRootRatio`	number (0-1)	`0.25`	Fração máxima de tickets sem dependências (roots). Roots demais significam que o plano subespecifica a ordenação.
`topology.maxLeafRatio`	number (0-1)	`0.25`	Fração máxima de tickets dos quais nada depende (leaves). Leaves demais significam que o plano é uma lista plana, não um grafo.

Cobertura de blueprint e validade das dependências são verificadas durante a cross-validation (todo blueprint de cobertura por ticket deve estar vinculado por pelo menos 2 tickets; referências circulares, quebradas e órfãs são rejeitadas) — são verificações estruturais, não limites configuráveis pelo usuário.

🔬 Para engenheiros: Estes são os parâmetros de tuning do loop de controle do planning descrito em Fundamentos de Engenharia. Os thresholds por camada definem a zona de aceitação em cada nível do plano. Aumentar um limite aperta a tolerância — o sistema requer menos desvio da spec ideal antes de passar.

Gates do Assay por Ticket

Quando um agente chama complete_work_session, o implementation lifecycle roda quatro gates de avanço contra o trabalho entregue do ticket. Cada gate pode ser ligado/desligado individualmente. Um ticket não avança para done até que todos os gates habilitados passem.


{
  "gates": {
    "acceptance": true,
    "step": true,
    "file": true,
    "test": true
  },
  "maxRetries": 7,
  "skipStepsCheck": false,
  "validateFiles": "local"
}

Detalhes dos Gates

Gate	O que verifica
`acceptance`	Todos os critérios de aceite do ticket foram satisfeitos?
`step`	Todos os passos de implementação do ticket foram completados?
`file`	Todas as mudanças esperadas de arquivo (criações, modificações, exclusões) foram registradas?
`test`	Resultados de teste foram submetidos para o ticket quando ele os exige?

⚠️ Desabilitar um gate deixa o lifecycle avançar além daquela dimensão sem sua verificação. Se você desabilitar acceptance, o assay não verificará se o ticket realmente atendeu seus critérios declarados. Desabilite deliberadamente, não casualmente.

Opções do Lifecycle

Opção	Tipo	Padrão	Descrição
`maxRetries`	number	`7`	Orçamento de retentativas: após esse número de tentativas de avanço falhas numa work session, o lifecycle tranca a sessão num estado só de discovery e exige intervenção manual. Isso previne loops infinitos em tickets fundamentalmente travados.
`skipStepsCheck`	boolean	`false`	Quando `true`, o gate de completude de passos é pulado — o agente pode avançar sem cada passo de implementação marcado como concluído.
`validateFiles`	`"agent"` \| `"local"`	`"local"`	Quem valida as mudanças de arquivo registradas. `"agent"` confia no conjunto auto-reportado pelo agente; `"local"` faz o MCP-local verificar as mudanças contra o worktree.

Pesos de Progresso

O score de completude (progresso) por ticket é um agregado ponderado das dimensões do ticket. A struct de quatro chaves de pesos é:


{
  "weights": {
    "steps": 0.55,
    "ac": 0.3,
    "tests": 0.15,
    "files": 0
  }
}

As dimensões de step e file são unificadas — o progresso de um passo requer seus arquivos vinculados registrados como matched — então files carrega 0 por padrão enquanto steps absorve o peso combinado. Coerência é uma fórmula fixa separada e não carrega pesos.

Perfis de Configuração

Diferentes situações pedem diferentes configurações. Aqui estão configurações comuns.

Prototipagem

Velocidade importa mais que cerimônia. Limites menores, pular a verificação de passos.


{
  "thresholds": { "global": 60, "specification": 60, "epic": 55, "ticket": 55 },
  "gates": { "acceptance": true, "step": false, "file": true, "test": false },
  "skipStepsCheck": true
}

Por que manter os limites significativos mesmo para protótipos? Porque uma decomposição ruim desperdiça mais tempo do que um review rápido custa. Baixar os limites permite passar com planos mais brutos enquanto ainda captura dependências circulares e épicos vazios.

Desenvolvimento Padrão

Os padrões. Equilibrado entre rigor e velocidade. Bom para equipes começando com o SpecForge.


{
  "thresholds": { "global": 80, "specification": 80, "epic": 70, "ticket": 70 },
  "gates": { "acceptance": true, "step": true, "file": true, "test": true },
  "maxRetries": 7,
  "validateFiles": "local"
}

Nível Produção

Máximo rigor. Limites mais altos, todos os gates ligados, validação local de arquivos. Use para especificações que serão entregues a usuários.


{
  "thresholds": { "global": 90, "specification": 90, "epic": 85, "ticket": 85 },
  "gates": { "acceptance": true, "step": true, "file": true, "test": true },
  "maxRetries": 7,
  "validateFiles": "local"
}

A diferença-chave: thresholds mais altos capturam planos marginais que passariam raspando com 80. Manter todos os gates ligados e validateFiles: "local" significa que o trabalho entregue de cada ticket é verificado contra o worktree, não aceito pela palavra do agente.

Configurando padrões de qualidade

Padrões de qualidade são configurações do validator e do implementation-lifecycle no nível do projeto, não chaves do specforge configure — o comando configure aceita apenas as cinco chaves planas documentadas na referência da CLI (mcpOutputFormat, projectId, specificationId, autoSetContext, defaultProjectId). Os limites de prontidão por camada e as configurações de gate são gerenciados pelo painel ou editando o .specforge/config.json.

📖 Padrões de qualidade se aplicam no nível do projeto. Todas as especificações dentro de um projeto herdam a mesma configuração de review. Para o schema completo de configuração, veja Schema de Configuração.

Veja Também

Gates de Qualidade — Como os dois gates avaliam especificações e o que cada dimensão de pontuação significa
Schema de Configuração — Referência completa de schema para todos os arquivos de configuração
Ciclos de Vida — Onde os gates se encaixam nos dois lifecycles