W6: O Stack Ideal

# PRD — [Nome da Feature]

## Critérios de aceite (SMART)
- [ ] Tempo de resposta do endpoint POST /auth < 200ms no p95 sob 500 req/s
- [ ] Taxa de erro < 0.1% em 1 hora de carga contínua
- [ ] Fluxo de recuperação de senha completo em < 3 cliques
- [ ] Compatível com WCAG 2.1 AA (acessibilidade)
- [ ] Dados de PII encriptados em repouso (AES-256)

## Fora de escopo (explícito)
- SSO via SAML (próxima fase)
- Login social (backlog)

## Restrições técnicas conhecidas
- PostgreSQL 15, sem migração de schema destrutiva
- Deploy em edge functions Vercel

# Iniciar a fase de discovery
/gsd:discuss-phase

# Claude vai perguntar sobre: edge cases, estados de erro,
# integrações externas, volume esperado, rollback strategy,
# dependências de outras features, critérios de performance

# ADR-001: JWT vs Session Tokens para autenticação

**Data:** 2025-03-15
**Status:** Aceito

## Contexto
Sistema SaaS multi-tenant, 50K usuários ativos, edge functions sem estado.

## Decisão
JWT com refresh token rotation (RFC 7519). Access token com TTL de 15min,
refresh token com TTL de 7 dias armazenado em httpOnly cookie.

## Consequências
+ Stateless: compatível com edge runtime sem Redis
+ Revogação granular via refresh token blacklist (Redis opcional)
- Overhead de validação de assinatura em cada request
- Payload público: não colocar dados sensíveis no token

## Alternativas descartadas
- Sessions com Redis: requer infraestrutura adicional, custo operacional
- Opaque tokens: requer lookup no DB em cada request

# Gerar UI-SPEC.md baseado no PRD
/gsd:ui-phase

# Resultado: UI-SPEC.md com:
# - Layout wireframe em ASCII
# - Componentes shadcn/ui mapeados
# - Estados: default, loading, error, empty
# - Paleta: zinc/slate, accent único
# - Tokens tipográficos: Geist Sans + Geist Mono

// DOMAIN: sem dependências externas
// src/domain/auth/entities/User.ts
export class User {
  constructor(
    readonly id: UserId,
    readonly email: Email,
    private passwordHash: PasswordHash
  ) {}

  verifyPassword(candidate: string): boolean {
    return this.passwordHash.verify(candidate);
  }

  static create(email: string, password: string): User {
    return new User(
      UserId.generate(),
      Email.parse(email),        // lança InvalidEmailError
      PasswordHash.bcrypt(password)
    );
  }
}

// PORT: interface de contrato (sem implementação)
// src/domain/auth/ports/UserRepository.ts
export interface UserRepository {
  findByEmail(email: Email): Promise;
  save(user: User): Promise;
  delete(id: UserId): Promise;
}

// ADAPTER: implementação concreta (depende da infra)
// src/infra/postgres/PostgresUserRepository.ts
export class PostgresUserRepository implements UserRepository {
  constructor(private readonly db: PrismaClient) {}

  async findByEmail(email: Email): Promise {
    const row = await this.db.user.findUnique({
      where: { email: email.value }
    });
    return row ? UserMapper.toDomain(row) : null;
  }
  // ...
}

// src/domain/auth/ports/__tests__/UserRepository.contract.ts
// Contrato: qualquer implementação de UserRepository DEVE passar nesses testes

import type { UserRepository } from '../UserRepository';

export function userRepositoryContract(
  createRepo: () => UserRepository,
  cleanup: () => Promise
) {
  let repo: UserRepository;

  beforeEach(() => { repo = createRepo(); });
  afterEach(cleanup);

  it('persiste e recupera usuário por email', async () => {
    const user = User.create('alice@example.com', 'S3cr3t!');
    await repo.save(user);

    const found = await repo.findByEmail(Email.parse('alice@example.com'));
    expect(found).not.toBeNull();
    expect(found!.id.value).toBe(user.id.value);
  });

  it('retorna null para email inexistente', async () => {
    const found = await repo.findByEmail(Email.parse('ghost@example.com'));
    expect(found).toBeNull();
  });

  it('sobrescreve ao salvar usuário existente', async () => {
    const user = User.create('bob@example.com', 'P4ss!');
    await repo.save(user);
    await repo.save(user); // idempotente
    const found = await repo.findByEmail(Email.parse('bob@example.com'));
    expect(found).not.toBeNull();
  });
}

// Uso no teste do adapter concreto:
// PostgresUserRepository.test.ts
userRepositoryContract(
  () => new PostgresUserRepository(testDb),
  () => testDb.user.deleteMany()
);

# Orchestrator Master envia para cada subagente:

# Backend Agent — contexto inicial:
# - REQUIREMENTS.md
# - ADR.md
# - src/domain/ (entities + ports)
# - Testes de contrato já escritos
# - Instrução: "Implemente os adapters em TDD. RED já existe. GREEN e REFACTOR são sua responsabilidade."

# Frontend Agent — contexto inicial:
# - UI-SPEC.md
# - API_CONTRACT.md (gerado pelo Backend Agent ao completar)
# - Instrução: "Implemente a UI conforme UI-SPEC.md. Dados via API_CONTRACT.md."

# Security Agent — contexto inicial:
# - REQUIREMENTS.md
# - ADR.md
# - OWASP checklist ativa
# - Instrução: "Audite em paralelo. Reporte em SECURITY_FINDINGS.md."

# API_CONTRACT.md — gerado pelo Backend Agent

## POST /api/auth/login
**Request:**
```json
{ "email": "string", "password": "string" }
```
**Response 200:**
```json
{ "accessToken": "string", "expiresIn": 900 }
```
**Response 401:**
```json
{ "error": "INVALID_CREDENTIALS", "message": "string" }
```
**Headers de resposta:**
- `Set-Cookie: refreshToken=...; HttpOnly; Secure; SameSite=Strict`

## GET /api/auth/me
**Headers:** `Authorization: Bearer {accessToken}`
**Response 200:**
```json
{ "id": "string", "email": "string", "createdAt": "ISO8601" }
```
**Response 401:** Token inválido ou expirado

# TypeScript strict: nenhum erro permitido
npx tsc --noEmit --strict

# ESLint: zero warnings (warnings viram erros no CI)
npx eslint . --max-warnings 0

# Configuração tsconfig.json para projetos W6:
# "strict": true
# "noUncheckedIndexedAccess": true
# "exactOptionalPropertyTypes": true

# Rodar apenas unit tests (padrão de naming: *.unit.test.ts)
npx vitest run --reporter=verbose src/domain

# Coverage com threshold que falha o build se não atingido
npx vitest run --coverage --coverage.thresholds.lines=80 \
  --coverage.thresholds.functions=85 \
  --coverage.thresholds.branches=75 \
  src/domain

# vitest.config.ts
coverage: {
  provider: 'v8',
  thresholds: { lines: 80, functions: 85, branches: 75 },
  include: ['src/domain/**'],
  exclude: ['**/*.d.ts', '**/__tests__/**']
}

# Testcontainers sobe o Postgres real para os testes
# Padrão de naming: *.integration.test.ts
npx vitest run --reporter=verbose src/infra

# setup de testcontainer:
# src/test/setup-integration.ts
import { PostgreSqlContainer } from '@testcontainers/postgresql';

let container: PostgreSqlContainer;

beforeAll(async () => {
  container = await new PostgreSqlContainer('postgres:15')
    .withDatabase('testdb')
    .start();
  process.env.DATABASE_URL = container.getConnectionUri();
  await runMigrations(process.env.DATABASE_URL);
}, 60_000);

afterAll(async () => {
  await container.stop();
});

# Cypress em modo headless no CI
npx cypress run --headless --browser chrome

# cypress.config.ts
export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    // Apenas jornadas críticas: login, checkout, onboarding
    // Não testar cada componente — isso é responsabilidade dos unit tests
  },
  video: false,  // desativa no CI para performance
  screenshotOnRunFailure: true
});

// k6/load.js — baseline: 500 req/s por 5 minutos
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '1m', target: 500 },   // ramp up
    { duration: '3m', target: 500 },   // sustain
    { duration: '1m', target: 0 },     // ramp down
  ],
  thresholds: {
    http_req_duration: ['p95<200'],      // p95 < 200ms
    http_req_failed: ['rate<0.001'],     // < 0.1% erro
  },
};

export default function () {
  const res = http.post('http://localhost:3000/api/auth/login', JSON.stringify({
    email: 'load-test@example.com',
    password: 'LoadTest123!'
  }), { headers: { 'Content-Type': 'application/json' } });

  check(res, { 'status is 200': (r) => r.status === 200 });
  sleep(0.1);
}

// k6/stress.js — descobrir ponto de ruptura
export const options = {
  stages: [
    { duration: '2m', target: 1000 },
    { duration: '3m', target: 2000 },
    { duration: '2m', target: 5000 },  // ponto de ruptura esperado aqui
    { duration: '5m', target: 0 },     // observar degradação graceful
  ],
  thresholds: {
    // Stress test: não falha o build — gera relatório de capacidade
    http_req_duration: ['p99<5000'],
  },
};

# Gerar relatório consolidado antes de avançar para Fase 4
npm run test:report

# package.json scripts sugeridos:
"test:ci": "tsc --noEmit && eslint . --max-warnings 0 && vitest run --coverage && cypress run --headless && k6 run k6/load.js",
"test:report": "vitest run --reporter=json --outputFile=test-results/unit.json && open coverage/index.html"

# Deploy de preview — URL única por branch/commit
vercel --preview

# A URL gerada é enviada para o PM junto com:
# 1. Link para o REQUIREMENTS.md (critérios de aceite originais)
# 2. Lista de testes que passaram (relatório da Fase 3)
# 3. SECURITY_FINDINGS.md (findings do Security Agent)
# 4. Instruções específicas de como testar cada critério

# PM Review — [Feature Name] — [Data]

## Resultado geral: [ ] APROVADO  [ ] REJEITAR COM FEEDBACK

## Critérios de aceite

| Critério | Status | Evidência / Observação |
|---|---|---|
| Tempo de resposta < 200ms p95 | APROVADO | Testei com DevTools: 145ms p95 |
| Taxa de erro < 0.1% | APROVADO | 0 erros em 30 min de uso |
| Fluxo em < 3 cliques | REJEITADO | Recuperação de senha exige 4 cliques |
| WCAG 2.1 AA | APROVADO | aXe extension: 0 violations |
| PII encriptado em repouso | A VERIFICAR | Requer confirmação do Security Agent |

## Feedback específico (apenas se REJEITADO)

### Critério: Fluxo de recuperação de senha
**Problema:** Tela de confirmação de email tem um passo extra desnecessário.
**Critério original:** "Fluxo de recuperação em < 3 cliques"
**Sugestão:** Remover a tela de "email enviado com sucesso" e redirecionar diretamente.
**Bloqueante:** Sim — não vai para prod assim.

## Próximos passos
- [ ] Time ajusta o fluxo de recuperação de senha
- [ ] Novo deploy de preview
- [ ] Re-validação apenas do critério afetado

# Executa o processo completo de ship
/gsd:ship

# Internamente, /gsd:ship faz:
# 1. Verifica que todos os testes estão passando no estado atual
# 2. Cria o PR via gh pr create com template padronizado
# 3. Executa o code-reviewer final pass
# 4. Roda npm audit para OWASP A06
# 5. Checa SECURITY_FINDINGS.md — findings bloqueantes impedem merge
# 6. Gera o CHANGELOG entry
# 7. Aguarda aprovação de reviewer humano antes de merge

# CLAUDE.md — seção de code review padrão W6

## Code Review Checklist (obrigatório antes de qualquer PR)

### Clean Code
- [ ] Funções com responsabilidade única (< 20 linhas na maioria dos casos)
- [ ] Nomes que revelam intenção (sem abbreviações obscuras)
- [ ] Zero comentários que explicam o que o código faz (apenas o porquê)
- [ ] Sem números mágicos — use constantes nomeadas

### SOLID
- [ ] SRP: nenhuma classe com mais de uma razão para mudar
- [ ] OCP: extensão via interface, não modificação de classe existente
- [ ] LSP: subclasses substituem superclasses sem surpresas
- [ ] ISP: interfaces pequenas e focadas (max 3-5 métodos)
- [ ] DIP: injeção de dependência via construtor, não instanciação direta

### Hexagonal Arch
- [ ] Domain core sem imports de infra (prisma, express, etc.)
- [ ] Adapters implementam Ports — nunca ao contrário
- [ ] Use cases dependem de Ports, nunca de Adapters diretamente

# Audit obrigatório — vulnerabilidades críticas e high bloqueiam o merge
npm audit --audit-level=high

# Se houver vulnerabilidades:
npm audit fix        # tenta auto-fix
npm audit fix --force  # USAR COM CUIDADO: pode introduzir breaking changes

# O que fazer com falsos positivos ou vulnerabilidades sem fix:
# 1. Criar .nsprc ou npm audit exception com justificativa documentada
# 2. Abrir issue de tracking com prazo de resolução
# 3. Revisor humano deve aprovar explicitamente a exceção

# Checklist de alertas antes de merge para main

# 1. Error rate alert: > 1% em 5 minutos → PagerDuty
# 2. P95 latência > 500ms por 3 minutos → Slack #incidents
# 3. CPU > 80% por 5 minutos → auto-scale trigger
# 4. DB connections > 80% do pool → alerta preventivo

# Vercel Observability — configurar antes do deploy prod:
# - Log drain para sistema centralizado
# - Speed Insights habilitado
# - Web Analytics habilitado para monitorar Core Web Vitals

# Post-Mortem — [Título do Incidente]

**Severidade:** P0 / P1 / P2
**Duração:** [início] → [resolução]
**Impacto:** X usuários afetados, R$ Y de receita impactada

## Timeline
- 14:23 — Deploy de prod (commit abc123)
- 14:31 — Primeiros erros no Sentry (error rate 12%)
- 14:35 — Alerta PagerDuty disparado
- 14:40 — Rollback executado via `vercel rollback`
- 14:45 — Sistema estável, investigação iniciada

## Root Cause
[Análise técnica objetiva — sem culpar pessoas]

## O que o W6 detectou / não detectou
- [ ] TypeScript strict: não detectou (runtime error, não type error)
- [ ] Testes de integração: não cobriram esse edge case
- [ ] Load test: cobriu o volume, não a combinação de inputs

## Ações corretivas
- [ ] Adicionar teste de regressão para o caso exato que falhou
- [ ] Adicionar ao load test o padrão de tráfego que causou o incidente
- [ ] Revisar cobertura de testes na área afetada

# Ao final da Fase 1, antes de spawnar agentes:
/compact

# O que preservar no CONTEXT.md antes de compactar:
# - Decisões arquiteturais tomadas (resumo dos ADRs)
# - Estrutura de diretórios acordada
# - Interfaces (Ports) definidas
# - Quais testes de contrato já existem e qual seu status
# - Dependências entre os agentes (qual aguarda o quê)

# Estrutura de arquivos de handoff no W6:
docs/
  REQUIREMENTS.md      # Fase 0 → Fase 1 (assinado pelo PM)
  ADR.md               # Fase 0 → todas as fases
  UI-SPEC.md           # Fase 0 → Frontend Agent
  API_CONTRACT.md      # Backend Agent → Frontend Agent
  SECURITY_FINDINGS.md # Security Agent → Fase 5 (ship gate)
  CONTEXT.md           # Orchestrator → /compact summary
  CHANGELOG.md         # Atualizado em cada ship

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "node scripts/quality-gate.mjs \"$CLAUDE_TOOL_INPUT_FILE_PATH\""},
          {"type": "command", "command": "node scripts/check-boundaries.mjs \"$CLAUDE_TOOL_INPUT_FILE_PATH\""}
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "node scripts/bash-guard.mjs"}]
      }
    ],
    "Stop": [
      {
        "hooks": [{"type": "command", "command": "node scripts/coverage-check.mjs"}]
      }
    ]
  }
}

#!/usr/bin/env node
// coverage-check.mjs — verifica cobertura mínima ao final de cada resposta
import { execSync } from 'node:child_process';

try {
  execSync(
    'npx vitest run --coverage --coverage.thresholds.lines=80 --coverage.thresholds.functions=80 --reporter=dot',
    { stdio: 'inherit' }
  );
  console.log('[coverage-check] OK: cobertura acima dos thresholds mínimos');
} catch {
  console.error('[coverage-check] AVISO: cobertura abaixo do mínimo (80% lines, 80% functions)');
  console.error('[coverage-check] Verifique: domain/ deve ter 80%+, use cases críticos 100%');
  // Warning, não bloqueia — o PM gate é quem decide
}