Mudança (Brownfield)

O que Mudança (Brownfield) faz?

Adicione uma mudança delimitada e revisável a uma especificação e base de código existentes sem escrever um novo PRD. Uma mudança produz uma proposta mais exatamente um pacote de quatro documentos de tarefas; após o QA passar, os deltas confirmados são gravados de volta na especificação e a proposta é arquivada. Esta skill é orientada a prompt: cada etapa tem um fallback manual e os scripts incluídos são auxiliares opcionais.

Posição no pipeline: spec-generator -> change -> task-decomposition -> plan-linter (Gate 1) -> review (Gate 2) -> dev -> qa -> converge -> arquivo.

especificação existente + mudança delimitada
  -> .specs/change-context/standards.md        (standards_extract.py; restrições implícitas)
  -> .specs/changes/<change-id>/proposal.md    (ciclo de vida: proposed -> applied -> archived)
  -> tasks/<change-id>/01..04                  (um contrato, um pacote)
  -> Gate 1 plan-linter -> Gate 2 review -> dev <-> qa -> convergir -> proposta arquivada

Quando usar

• Uma especificação existente ou base de código enviada precisa de uma mudança incremental: uma correção de bug, uma pequena funcionalidade, um ajuste de comportamento, um ajuste de NFR delimitado.
• A mudança pode reutilizar uma âncora #sec-* existente e se encaixa no orçamento de diff micro/padrão.
• Você deseja o loop proposta -> aplicar -> arquivar mantendo o protocolo de tarefas de 4 documentos deste repositório e os papéis de um proprietário por arquivo.

Não usar quando

• O trabalho é greenfield, ou nenhuma especificação upstream existe ainda: use prd-generator, depois spec-generator, depois task-decomposition.
• A mudança precisa de uma nova decisão de arquitetura, um novo limite de componente, uma nova invariante transversal ou uma seção de especificação totalmente nova (uma nova âncora #sec-*): encaminhe para spec-generator em vez de contrabandeá-la para uma mudança.
• Você só precisa fatiar uma especificação aprovada em tarefas: use task-decomposition.
• Você só precisa auditar pacotes ou propostas existentes: use plan-linter.
• A tarefa já está planejada e aguardando implementação/verificação: use dev / qa.

Entradas

• A especificação base: .specs/02-tech-spec.md (e suas partes modulares) por padrão.
• O requisito para a mudança delimitada, escrito pelo solicitante em linguagem simples.
• O relatório de convenções do repositório gerado na etapa 1.
• Opcional: o pacote de tarefas existente do qual a mudança continua, e os ADRs relevantes.

Saídas

Artefato	Proprietário após scaffolding	Propósito
.specs/change-context/standards.md	Ferramentas	Padrões determinísticos do repositório e restrições implícitas (gerado, nunca editado manualmente).
.specs/changes/<change-id>/proposal.md	Planejador	Proposta de mudança delimitada: motivação, diff incremental, área de impacto, invariantes/NFR, reversão, verificação.
.specs/changes/<change-id>/convergence.md	Ferramentas de convergência	Escrito após o QA passar; registra o que foi incorporado de volta à especificação.
tasks/<change-id>/01-contract.md ... 04-process.md	Planejador / Dev / QA / ferramentas	Exatamente um pacote de quatro documentos, reutilizando os modelos de decomposição de tarefas.

A proposta não é um PRD e não é uma especificação substituta. É um delta que nomeia as âncoras existentes que altera. Ciclo de vida completo e regras de dimensionamento: references/brownfield-protocol.md.

Fluxo de trabalho

1. Extrair padrões do repositório (uma vez por alteração de configuração):

   python .agents/skills/change/scripts/standards_extract.py --repo-root . --json
   python .agents/skills/change/scripts/standards_extract.py --repo-root . --check
   

   Leia .specs/change-context/standards.md antes de planejar. Sua seção "Restrições implícitas" é vinculativa: use apenas os comandos que ela evidencia, respeite a disposição declarada de testes, pisos de runtime e âncoras existentes. Código de saída 1 de --check significa que o relatório está desatualizado; regenere antes de planejar. Nunca edite manualmente o relatório.

2. Escaffoldar a proposta e um pacote de tarefas (a única etapa que escreve arquivos):

   python .agents/skills/change/scripts/scaffold_change.py \
     --change-id CHG-001-rate-limit \
     --title "Limitar taxa de tentativas de login" \
     --anchor "#sec-auth-tokens" \
     --kind modify \
     --size-class micro --estimated-lines 40 \
     --touch-files "modify:src/auth/rate_limit.py" \
     --repo-root .
   

   O scaffolder valida âncoras contra a especificação base, calcula base_spec_sha256, e delega para task-decomposition (scaffold_task.py) ou emite um pacote inline mínimo se ausente. Use --dry-run para pré-visualizar e --force para sobrescrever execuções descartáveis.

3. Planejador preenche a proposta e o contrato. Substitua guias na proposta (motivation, [CHG-<n>] hunks, caminhos, invariantes/NFR, reversão, verificação) e placeholders do contrato (module, adherence_adrs, dod, casos de borda, prosa de invariante). Não invente caminhos ou âncoras. Mantenha formulários de papel 02/03 em branco; mantenha proposta status: proposed.

4. Gate 1, depois Gate 2. Execute Gate 1 determinístico, depois revisão semântica independente:

   # Execute a partir da raiz do repositório. O helper do Gate 1 requer que a skill plan-linter esteja instalada.
   python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes
   python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-rate-limit --repo-root .
   

   Gate 1 deve passar antes da implementação; Gate 2 não deve relatar BLOCKED ou REQUEST CHANGES.

5. Implementar e verificar. Execute dev (apenas touch_files declarados, preencha 02, passe adiante) e qa (testes independentes em tests/acceptance/, preencha 03, um veredito). A proposta passa para applied assim que a implementação e a verificação passarem.

6. Convergir e arquivar. Após QA_PASSED, execute converge para anexar desvios confirmados a .specs/02-tech-spec.md, escreva convergence.md, mova o pacote para tasks/archive/, e defina o status da proposta como archived. Sem converge, execute a gravação de anexo idêntico manualmente.

Fallback manual (sem Python)

1. Monte a lista de padrões manualmente: configurações da raiz do repositório, árvores de teste/fonte, runtimes, âncoras #sec-*.
2. Copie assets/templates/proposal.template.md para .specs/changes/<change-id>/proposal.md, preencha cada token ({{...}}) e calcule base_spec_sha256.
3. Crie o pacote de quatro documentos tasks/<change-id>/ usando os modelos de task-decomposition ou o fallback em references/brownfield-protocol.md.
4. Execute as listas de verificação do Gate 1 / Gate 2 manualmente; registre evidências no pacote.
5. Siga as etapas 5–6 do fluxo de trabalho com os mesmos artefatos.

Lista de verificação do portão de qualidade

• Relatório de padrões gerado e atualizado (standards_extract.py --check sai com 0).
• Metadados da proposta completos, status: proposed, kind correto, base_spec_sha256 atualizado.
• Cada bloco [CHG-<n>] nomeia uma âncora #sec-* real que existe na especificação base.
• Existe exatamente um pacote de tarefas; change_id é igual ao id da proposta e origin_spec_anchor é uma das impact_anchors da proposta.
• Orçamento de diff respeitado: micro é 1 arquivo tocado (padrão 10-49 linhas); padrão é 1-3 arquivos (padrão 50-250 linhas). Números configuráveis na configuração do plan-linter.
• Gate 1 passa no contrato preenchido e a proposta está aberta (proposed/applied).
• Revisão do Gate 2 não tem achados bloqueadores; revisor é independente e somente leitura.
• Dev implementou apenas touch_files; QA emitiu exatamente um veredito com evidências.
• Converge anexou deltas à especificação e a proposta está archived.

Regras anti-alucinação

• Nunca invente caminhos de arquivos. Cada entrada touch_files deve ser um arquivo existente para modify ou um novo arquivo em um diretório existente para create (relativo ao repositório, com barras normais).
• Cada hunk de diff nomeia uma âncora real. Reutilize uma âncora #sec-* existente; o scaffolder e o linter rejeitam âncoras ausentes ou desviadas.
• Não invente comandos ou convenções. Apenas comandos evidenciados pela configuração declarada (o relatório de padrões) podem aparecer no DoD do contrato.
• Uma mudança estrutural escala. Se a mudança precisar de uma nova seção/âncora de especificação, um novo componente, um novo ADR ou uma alteração de invariante, pare e use spec-generator.
• Não exagere nos portões. Gate 1 é contabilidade determinística, Gate 2 é revisão de prompt; git e CI permanecem autoritativos.

Scripts auxiliares

• scripts/standards_extract.py — extrator de padrões determinístico; escreve .specs/change-context/standards.md (--json, --check, --dry-run, --version).
• scripts/scaffold_change.py — cria proposta e um pacote de tarefas (--dry-run, --force, --json, --version).
• scripts/lint_change.py — verificação de consistência proposta/pacote e desvio da especificação base (--json, --version).

Todos os helpers são apenas stdlib, resolvem seu próprio diretório e saem com 0 (sucesso), 1 (falha de gate), 2 (erro de uso), 3 (erro inesperado).

Tratamento de falhas

• Especificação base ausente: Pare. Uma mudança brownfield requer uma especificação base; scaffold sai com 2.
• Âncora desconhecida: Pare e reutilize uma âncora existente, ou encaminhe para spec-generator.
• Relatório desatualizado ou desvio de especificação (saída 1): Regere o relatório, rebaseie a proposta, reexecute Gate 1; nunca edite manualmente base_spec_sha256.
• Diretório de mudança existe: Reexecute com --force apenas se descartável; caso contrário, edite a proposta existente.
• Scripts indisponíveis: Siga o fallback manual; o fluxo de trabalho é orientado a prompt.

Limites honestos

• O relatório de padrões descreve a configuração declarada, não necessariamente a prática imposta; é um prompt para o Planejador, não prova de conformidade.
• base_spec_sha256 detecta qualquer alteração de byte na especificação base; após a convergência, a proposta arquivada está isenta de verificações de desvio.
• Scripts opcionais são contornáveis; CI mais permissões do repositório permanecem autoritativos.