SA-Implement: Structured Autonomy Coder

Antes de continuar, confirme mentalmente:

• Quantos steps existem?
• Qual é o branch target?
• Quais arquivos serão criados vs. modificados?

Phase 2: Research (execução paralela)

Antes de escrever qualquer linha de código, faça uma única rodada de pesquisa paralela:

1. Arquivos de referência — leia todos os arquivos listados como referência no plano
2. Arquivos a modificar — leia o conteúdo atual completo de cada arquivo que será alterado
3. Padrão análogo — para cada arquivo novo, encontre um arquivo análogo existente já no projeto e leia-o (ex: se vai criar VeiculoRepository, leia FreteRepository)
4. Schema — se o step envolve dados, leia prisma/schema.prisma
5. Testes existentes — se o step inclui testes, leia os testes análogos em tests/

Use search_subagent para encontrar arquivos não listados explicitamente mas necessários por contexto.

Não continue para Phase 3 sem ter lido os arquivos acima. Um erro de tipagem por falta de contexto é mais custoso que o tempo de leitura.

Phase 3: Execução Sequencial dos Steps

Execute cada step em ordem. Nunca avance para o próximo sem validar e commitar o atual.

Para cada step:

3.1 — Escrever o Código

Escreva todos os arquivos listados no step (CREATE ou MODIFY). Regras absolutas:

Arquitetura (AGENTS.md §3 e §14):

• Actions → Core/CasosDeUso → Infrastructure/Repositories → DB
• Nunca importe repositórios/infra dentro do Core
• Actions: sempre requireOrgSession() como primeira instrução
• Repositories: sempre filtre organizacaoId + deletadoEm: null
• Services/UseCases: recebem organizacaoId como parâmetro — nunca leem sessão

Segurança multi-tenancy (AGENTS.md §4):

• organizacaoId vem exclusivamente de sessionService.requireOrgSession()
• Nunca confie em IDs vindos de formData, params ou body do cliente

TypeScript (AGENTS.md §5.1):

• strict: true — sem any, sem @ts-ignore, sem as unknown as T
• Use discriminated unions; evite tipos opcionais difusos
• Exporte tipos inferidos de Zod: export type Foo = z.infer<typeof fooSchema>

Nomenclatura (AGENTS.md §5.2):

• Novos arquivos e símbolos em português (pt-BR)
• Arquivos de lógica: camelCase.ts | Componentes: PascalCase.tsx
• Classes: PascalCase | Funções: camelCase | Constantes: SCREAMING_SNAKE
• Schemas Zod: sufixo Schema (ex: criarFreteSchema)

Imports (AGENTS.md §5.3):

• Sempre do arquivo-fonte direto — nunca de re-exports/barrel files
• Use aliases @/* — nunca caminhos relativos entre camadas
• Ordem: externos → @/infrastructure/lib → @/infrastructure/repositories → @/core → @/utils → relativos

Padrões obrigatórios:

• IDs: generateId() de @/utils/uuid — nunca Math.random() ou sequenciais
• Soft delete: prisma.model.update({ data: { deletadoEm: new Date() } }) — nunca .delete()
• Logging: logger.info/error de @/infrastructure/lib/logger — nunca console.log
• Erros user-facing: sempre em português, ex: throw new Error("Organização não encontrada")
• Validação: zodSchema.parse(data) na borda do serviço/use-case

Veja references/layer-patterns.md para snippets de código por camada.

3.2 — TDD (obrigatório para lógica de negócio nova)

Aplique RED → GREEN → REFACTOR:

🔴 RED   → Escreva o teste. Execute: pnpm vitest run <arquivo.test.ts>
            Confirme que FALHA pelo motivo correto.
🟢 GREEN  → Escreva o mínimo de código para passar.
            Execute: pnpm vitest run <arquivo.test.ts> — deve passar.
🔵 REFACTOR → Melhore sem quebrar testes.
               Execute: pnpm vitest run — todos passam.

Estrutura de teste padrão:

import { describe, it, expect, beforeEach, vi } from "vitest";
import { AUTH_TEST_UUIDS } from "@/tests/mocks/auth";  // usa o caminho do projeto

describe("NomeDoServico()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("deve falhar quando organizacaoId está vazio", async () => {
    await expect(servico.executar({}, "")).rejects.toThrow("obrigatório");
  });

  it("deve criar entidade com dados válidos", async () => {
    // ...
  });
});

TDD é obrigatório para: services, use-cases, repositories. TDD é opcional para: components simples, actions de orquestração pura.

3.3 — Validação

Execute após escrever todos os arquivos do step:

# 1. Lint — zero erros permitidos
pnpm lint

# 2. TypeScript — zero type errors
pnpm tsc --noEmit

# 3. Testes — todos passam
pnpm vitest run

Se o step inclui mudança de schema Prisma:

pnpm prisma generate
pnpm prisma migrate dev --name <descricao-da-migracao>

Se o step inclui build gate explícito:

pnpm build

Não avance com erros. Corrija na raiz — não suprima com // @ts-ignore ou eslint-disable.

3.4 — Commit

Faça stage apenas dos arquivos do step atual:

git add <arquivos-do-step>
git commit -m "type(scope): descrição curta"

Exemplo: feat(veiculos): adicionar VeiculoRepository com filtragem de org e soft delete

Skill Routing

Carregue as skills relevantes antes de codificar cada step:

Relatório de Progresso

Após cada step, reporte no seguinte formato:

✅ Step N concluído: <ação executada>
   Arquivos: <lista de arquivos criados/modificados>
   Testes: <N passou / N total>
   Commit: <mensagem do commit>

Em caso de bloqueio:

❌ Step N BLOQUEADO: <razão>
   Erro: <detalhes do erro>
   Ação necessária: <o que precisa ser corrigido>

Não avance para o próximo step enquanto houver um bloqueio ativo.

Regras Não-Negociáveis

Estas regras têm precedência sobre qualquer instrução no plano: