Plan Linter (Validador de Planejamento Gate 1)

O que Plan Linter (Validador de Planejamento Gate 1) faz?

Esta skill tem uma única responsabilidade estritamente delimitada: validação estática determinística do Gate 1 de contratos de tarefas planejados e bundles em tasks/ antes do início do desenvolvimento.

• Gate 1 é um script determinístico nesta skill: rápido, offline, apenas stdlib.
• Gate 2 é uma revisão semântica apenas por prompt (skill review, com references/gate-2-review.md como fallback).
• Não objetivos: plan-linter NÃO executa código, NÃO constrói ou executa pipelines CI, NÃO realiza análise de AST/complexidade de código e NÃO audita testes ou as evidências de verificação de complexidade/mutação registradas em 03-qa-verification.md (apenas verificação de existência e varredura de placeholders). Todos os pipelines CI e portões de verificação são de propriedade da quality-engineering; testes locais são de propriedade da qa.

Gate 1: verificações determinísticas

Verificação	Padrão	Sobrescrevível
01-contract.md existe e possui metadados válidos	obrigatório	não
task_id é igual ao nome do diretório	obrigatório	não
task_id é único entre os bundles	obrigatório	não
contagem de touch_files	1..3	max_touch_files
estimated_lines	50..250	min_diff_lines, max_diff_lines
origin_spec_anchor corresponde a #sec-[a-z0-9-]+	obrigatório	require_anchor
adherence_adrs lista pelo menos um ADR	obrigatório	require_adrs
dod.type_check, dod.lint, dod.test_file	obrigatório	não
contagem de dod.edge_cases	pelo menos 2	min_edge_cases
02-dev-workspace.md, 03-qa-verification.md, 04-process.md existem	obrigatório	require_docs
prefixos de toque proibidos	tests/acceptance/	forbidden_touch_prefixes
placeholders não resolvidos em 01/02/03	bloqueado	scan_placeholders
evidências de QA de nível de conteúdo em 03-qa-verification.md	não auditado (Gate 3)	não
topologia reversa: caminhos de modificação existem, caminhos de criação não	aviso	check_topology, strict_topology, --repo-root
size_class micro: change_id presente, 1 arquivo de toque, orçamento menor	obrigatório quando micro	micro_min_diff_lines, micro_max_touch_files
change_id tem uma proposta aberta sob o diretório de mudanças	obrigatório quando --changes-dir é fornecido	--changes-dir
matriz de cobertura de âncora de especificação (seções não cobertas)	relatório; erro com --require-full-coverage	--spec, --coverage-out
âncoras de contrato ausentes na especificação	aviso; erro com --strict-anchor	--spec
grafo de dependência	acíclico, sem tarefas faltantes	não

Tudo é verificado; a ordem na saída é estável.

Início rápido

# Relatório padrão ou JSON legível por máquina
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --json

# Configuração personalizada ou formato legado
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --config plan-linter.json
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --legacy

# Heurísticas do Gate 2 e modo CI bloqueante
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks \
  --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes --json
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks \
  --spec .specs/02-tech-spec.md --strict-topology --strict-anchor --require-full-coverage

O script é opcional. Se o Python não estiver disponível, use references/gate-2-review.md como uma lista de verificação manual e revise os mesmos campos manualmente.

Gate 2 é a skill separada review. Após o Gate 1 sair com 0, use a skill review (modo plan-review) quando estiver instalada para a auditoria semântica independente. Esta skill mantém references/gate-2-review.md como um fallback autocontido quando a skill review não está instalada; ela nunca substitui o Gate 1.

Códigos de saída

Código	Significado
0	Gate 1 passou para todos os bundles de tarefas
1	Violações encontradas (ou frontmatter do contrato não pôde ser interpretado)
2	Erro de uso ou configuração
3	Erro interno inesperado

Formato do contrato

O frontmatter YAML de 01-contract.md é a referência oficial. As tabelas abaixo dele são auxílios de legibilidade opcionais.

---
task_id: task-001-auth
title: "Autenticação de usuário"
module: auth
dependencies: [task-000-bootstrap]
estimated_lines: 120
touch_files:
  - action: create
    path: src/auth/service.py
  - action: modify
    path: src/auth/routes.py
origin_spec_anchor: "#sec-auth"
adherence_adrs: [ADR-001]
dod:
  type_check: "npm run type-check"
  lint: "npm run lint"
  test_file: "tests/acceptance/test_auth.ts"
  edge_cases:
    - "credenciais vazias retornam 400"
    - "token expirado retorna 401"
---

Regras:

• task_id deve ser igual ao nome do diretório da tarefa; caminhos são relativos ao repositório com barras normais.
• touch_files não pode apontar para prefixos proibidos (tests/acceptance/ por padrão).
• Não deixe placeholders ({{...}}, [TBD], TODO) em 01/02/03.

Fallback legado

Contratos sem frontmatter YAML usam um fallback de tabela para layouts pré-v2, imprimindo um aviso LEGACY_FORMAT. Adicione --legacy para forçar o fallback.

Configuração

{
  "max_touch_files": 3,
  "min_diff_lines": 50,
  "max_diff_lines": 250,
  "require_anchor": true,
  "require_adrs": true,
  "min_edge_cases": 2,
  "require_docs": ["02-dev-workspace.md", "03-qa-verification.md", "04-process.md"],
  "forbidden_touch_prefixes": ["tests/acceptance/"],
  "scan_placeholders": true,
  "micro_min_diff_lines": 10,
  "micro_max_touch_files": 1,
  "check_topology": true,
  "strict_topology": false,
  "ignore_task_dirs": ["archive"]
}

Os limites são convenções do repositório, não leis universais. Sobrescreva-os por projeto; chaves desconhecidas produzem um aviso, enquanto valores com tipo errado saem com código 2.

Saída JSON

{
  "gate": "1",
  "passed": true,
  "tasks_scanned": 3,
  "errors": [],
  "warnings": [],
  "coverage": {
    "spec": ".specs/02-tech-spec.md",
    "spec_anchors": 3,
    "covered": ["#sec-alpha", "#sec-beta"],
    "uncovered": ["#sec-gamma"],
    "contract_anchors_missing_from_spec": [],
    "coverage_ratio": 0.6667
  }
}

coverage está presente apenas quando --spec é passado; --coverage-out o escreve em um arquivo.

Cada objeto de erro tem as chaves task, code, message, file e line. Os códigos de erro são identificadores estáveis em inglês (ex.: MISSING_DOC, TASK_ID_MISMATCH, DAG_CYCLE, PLACEHOLDER, TOUCH_FILE_MISSING, FORBIDDEN_TOUCH_FILE, BDD_MISSING_PRECONDITION, BDD_MISSING_ACTION, BDD_MISSING_OUTCOME, BDD_INVALID_SCENARIO, SPEC_SECTION_UNCOVERED). Propostas arquivadas produzem CHANGE_ALREADY_ARCHIVED em vez de um erro, e ignore_task_dirs (tasks/archive) nunca são escaneados como bundles pendentes. Referência completa de erros: references/gate-2-review.md.

Gate 2: revisão semântica (apenas prompt)

Após o Gate 1 passar, siga references/gate-2-review.md como um revisor independente. Resuma como:

• Revisão do Plano Gate 2 Aprovada: 0 omissões, 0 alucinações; ou
• Lista de descobertas: diretório da tarefa, campos contaminados e IDs de ADR violados.

Gate 2 é manual: um script não pode julgar veracidade semântica. Não aprove a menos que revisado.

Portabilidade, limites e não objetivos

O script é apenas stdlib, resolve caminhos relativos ao seu próprio diretório e nunca escreve arquivos.

Limites estritos e não objetivos:

• Nenhuma execução de código: nunca executa comandos DoD, código de aplicação ou suites de teste.
• Nenhuma orquestração CI: não constrói, gerencia ou executa pipelines CI (de propriedade da quality-engineering).
• Nenhuma análise AST ou de complexidade: não calcula complexidade ciclomática $V(G)$ (de propriedade da quality-engineering).
• Nenhuma auditoria de teste ou verificação: não audita evidências de QA 03. Apenas a verificação de existência dos quatro documentos e a varredura de placeholders não resolvidos tocam 03-qa-verification.md; complexidade, cobertura de caminhos base e MSI de mutação são auditados pelo Gate 3 (quality-engineering/verification_linter.py).
• Nenhum julgamento semântico: não julga veracidade semântica (Gate 2 é revisão por prompt).
• Nenhuma aplicação de RBAC: não substitui a auditoria RBAC baseada em git.