spec-first-claude 0.6.0-beta.9 → 0.7.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-claude",
-  "version": "0.6.0-beta.9",
+  "version": "0.7.0-beta.1",
   "description": "Spec-first workflow kit for Claude Code — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-claude": "bin/cli.js"

package/templates/.claude/CHANGELOG.md

@@ -8,6 +8,100 @@
 
 ---
 
+## 0.7.0-beta.1 (2026-04-13) — Redesign v4 (BREAKING)
+
+Reestruturação arquitetural baseada em feedback de uso real do v3. TRD ressuscitado
+como peer do PRD, SDD eliminado, aprovação por persona. Pipeline continua unificado
+via `/sfw-start`.
+
+### Breaking
+
+- **TRD ressuscitado** — peer do PRD, aprovado pelo dev. Não é o TRD antigo
+  transiente: agora tem papel próprio (source técnica autoritativa).
+- **SDD eliminado** — camada intermediária desnecessária quando PRD+TRD são bem
+  estruturados. `specs/{nome}/` deriva direto de PRD+TRD. `docs/` atualizado via
+  `/merge-docs` a partir de PRD+TRD.
+- **Aprovação por persona** — PM aprova PRD (`prd_aprovado: true`), dev aprova TRD
+  (`trd_aprovado: true`). Flags no `.context.md`. Em time pequeno, user faz as 2
+  aprovações — não pula.
+- **Discovery obrigatório** — `/discovery` deixou de ser skill opcional e virou
+  passo obrigatório dentro do `/sfw-start`. Força entendimento antes da extração.
+- **PRD `empty` removido** — conceito obsoleto. Agora: scope puro-técnico tem
+  `prd_existe=false`; scope puro-produto tem `trd_existe=false`. Maioria tem ambos.
+- **backlog_extraido.md eliminado** — features futuras viram itens em PRD §11
+  Fora de Escopo com sugestão de `/sfw-start <nome>` próprio.
+- **Schema do `.context.md` mudou**: `prd_empty` → `prd_existe` + `prd_aprovado`;
+  adicionado `trd_existe` + `trd_aprovado`. Status fluxo tem novos estados:
+  `discovery_done → extract_done → prd_approved → trd_approved → design_done`.
+
+### Templates
+
+- `TRD.template.md` novo — 11 seções, organizado por área (§Sistema + §Área-X)
+- `PRD.template.md` refatorado — 13 seções puro-produto, sem conteúdo técnico
+- `sdd.template.md` deletado
+- `backlog-extraido.template.md` deletado
+- `context.template.md` schema v4
+- `extract-log.template.md` sem categorização "produto/tech" (obsoleta)
+- `specs/*.template.md` com ORIGEM atualizada: PRD+TRD em vez de SDD
+
+### Skills
+
+- `/sfw-start` — 2 aprovações + discovery obrigatório
+- `/extract` — gera PRD e/ou TRD conforme conteúdo dos insumos (Reader + Produto-Analyzer + Tech-Analyzer)
+- `/design` — consome PRD+TRD aprovados, gera docs/ (first-run) + specs/
+- `/merge-docs` — diff semântico PRD+TRD ↔ docs/ (agente Integrator promovido pra Opus)
+- `/plan` — entrada PRD+TRD+specs/, tasks com `Ref TRD` em vez de `Ref SDD`
+- `/publish` — adicionado TRD à whitelist; SDD removido
+
+### Agents
+
+- Doc Writer reescrito: fonte muda de "SDD §Sistema" para "PRD + TRD"
+- Coders (backend/frontend/db/infra) e Reviewers: refs de "SDD §X" → "TRD §X" ou "specs/{nome}/"
+
+### Migração de v3 (0.6.x) pra v4
+
+```bash
+# 1. Atualizar kit
+npx spec-first-claude@beta update
+
+# 2. Para cada scope em andamento: migrar .context.md
+#    - Remover `prd_empty`
+#    - Adicionar `prd_existe`, `trd_existe`, `prd_aprovado`, `trd_aprovado`
+#    - Se scope já tem SDD: extrair conteúdo técnico pra TRD.md manual
+
+# 3. SDDs antigos em workspace/Output/{nome}/sdd.md ficam como legado
+#    (nenhum skill v4 lê eles). Deletar quando confortável.
+```
+
+### Versionamento
+
+- Bump **minor** (0.6 → 0.7) pelo breaking. v3 (`0.6.0-beta.10`) permanece no npm
+  como histórico.
+- Publicado com tag `beta`. Promoção para `latest` apenas após validação em uso real.
+
+---
+
+## 0.6.0-beta.10 (2026-04-13)
+
+### `bootstrap-confluence.js` agora é idempotente
+
+Script agora lê `.mcp.json` existente e reusa valores da entry `atlassian` em
+vez de perguntar tudo de novo:
+
+- Se `CONFLUENCE_URL` já existe: mostra URL atual, pergunta "Manter? [S/n]"
+- Se `CONFLUENCE_USERNAME` já existe: mostra email atual, pergunta "Manter? [S/n]"
+- Se `CONFLUENCE_API_TOKEN` já existe: mostra token mascarado (`abcd…wxyz`), pergunta "Manter? [S/n]"
+- Default ENTER = manter. Responder `n` abre o prompt completo da informação.
+
+Se todos os 3 campos foram mantidos: detecta que nada mudou e **não reescreve**
+`.mcp.json` (evita dirty git). Se mudou algo: reescreve preservando outras
+entries MCP (Supabase, GitHub, etc.).
+
+Útil pra: reexecução após novo rebuild do MCP, rotação apenas do token, debug
+de setup sem perder credenciais já válidas.
+
+---
+
 ## 0.6.0-beta.9 (2026-04-13)
 
 ### CLI em pt-BR + dica de bootstrap-confluence no init

package/templates/.claude/adapters/SETUP.md

@@ -148,7 +148,7 @@ output:
       config:
         space_key: "ST"                # ← mesmo Space Key
         parent_page_id: "294931"       # ← Page ID da page Output
-      publishes: [PRD, SDD, Progresso]
+      publishes: [PRD, TRD, Progresso]
       mode: auto                       # ← auto | manual | off
       conflict_detection: version
       approval_mechanism: label
@@ -225,7 +225,7 @@ output:
       adapter: filesystem
       config:
         root_path: "workspace/Output"
-      publishes: [PRD, SDD, Progresso]
+      publishes: [PRD, TRD, Progresso]
       mode: auto
       conflict_detection: hash
       approval_mechanism: none
@@ -282,7 +282,7 @@ E coloque `mode: off` nos targets de Confluence.
          config:
            space_key: "ST"
            parent_page_id: "294931"
-         publishes: [PRD, SDD, Progresso]
+         publishes: [PRD, TRD, Progresso]
          mode: auto
    ```
 3. Re-rode `/extract`, `/design`, `/plan` — os artefatos locais serão publicados

package/templates/.claude/adapters/filesystem.md

@@ -259,7 +259,7 @@ output:
       adapter: filesystem
       config:
         root_path: "./workspace/Output"
-      publishes: [PRD, SDD, Progresso]
+      publishes: [PRD, TRD, Progresso]
       mode: auto
       conflict_detection: hash
       approval_mechanism: none
@@ -284,7 +284,7 @@ output:
       adapter: filesystem
       config:
         root_path: "./tests/fixtures/barbearia/actual_output"
-      publishes: [PRD, SDD, Progresso]
+      publishes: [PRD, TRD, Progresso]
       mode: auto
 ```
 

package/templates/.claude/adapters/naming.md

@@ -56,7 +56,7 @@ O `sfw.config.yml` define 2 templates de output:
 **`output_container`** é o agrupador. No Confluence vira uma page-mãe com
 children; no filesystem vira uma pasta.
 
-**`output_artifact`** é o item individual (PRD, SDD, Progresso). No
+**`output_artifact`** é o item individual (PRD, TRD, Progresso). No
 Confluence é title de uma child page; no filesystem é nome de arquivo
 (adapter adiciona `.md` automaticamente).
 

package/templates/.claude/adapters/registry.md

@@ -178,13 +178,13 @@ output:
       config:
         space_key: ST
         parent_page_id: "294931"
-      publishes: [PRD, SDD, Progresso]
+      publishes: [PRD, TRD, Progresso]
       mode: auto
     - name: local-mirror
       adapter: filesystem
       config:
         root_path: "./mirror"
-      publishes: [PRD, SDD, Progresso, backlog]
+      publishes: [PRD, TRD, Progresso]
       mode: auto
 ```
 

package/templates/.claude/agents/backend-coder.md

@@ -1,215 +1,215 @@
-# Agent: Backend Coder (.NET 8)
-
-> Especialista em desenvolvimento backend com .NET 8 / C#.
-> Implementa tasks da área BACK seguindo SDD + rules.md.
-
----
-
-## Identidade
-
-| Campo | Valor |
-|-------|-------|
-| Área | BACK |
-| Modelo padrão | Sonnet (S/M) / Opus (L) |
-| Lê | `specs/{nome}/contracts.md` (API, dados, regras) + `scenarios.md` (fluxos, CAs) + task + `rules.md` |
-| Nunca lê | PRD, PM, docs de outras áreas |
-
-## Stack de referência
-
-| Tecnologia | Versão | Uso |
-|-----------|--------|-----|
-| .NET | 8 LTS | Runtime + SDK |
-| C# | 12 | Linguagem |
-| ASP.NET Core | 8 | Web framework (Minimal APIs ou Controllers) |
-| Entity Framework Core | 8 | ORM (migrations, queries) |
-| xUnit | latest | Testes unit + integration |
-| FluentAssertions | latest | Assertions legíveis |
-| FluentValidation | latest | Validação de DTOs/requests |
-| MediatR | latest | CQRS / mediator (se SDD indicar) |
-| Serilog | latest | Logging estruturado |
-
-## Padrões obrigatórios
-
-### Estrutura do projeto
-```
-src/
-├── Api/                          ← Entry point (Program.cs, endpoints/controllers)
-│   ├── Endpoints/                ← Minimal API endpoint groups
-│   ├── Middleware/                ← Auth, error handling, logging
-│   └── Program.cs
-├── Application/                  ← Use cases, DTOs, validações
-│   ├── Commands/                 ← Write operations
-│   ├── Queries/                  ← Read operations
-│   ├── DTOs/
-│   └── Validators/               ← FluentValidation
-├── Domain/                       ← Entidades, regras de negócio, interfaces
-│   ├── Entities/
-│   ├── Enums/
-│   └── Interfaces/
-├── Infrastructure/               ← EF DbContext, repositories, serviços externos
-│   ├── Data/
-│   │   ├── Configurations/       ← EF entity configurations
-│   │   ├── Migrations/
-│   │   └── AppDbContext.cs
-│   ├── Repositories/
-│   └── Services/
-tests/
-├── Unit/                         ← Domain + Application
-├── Integration/                  ← API endpoints (WebApplicationFactory)
-└── Fixtures/
-```
-
-### Convenções de código
-
-| Regra | Exemplo |
-|-------|---------|
-| Namespaces seguem pastas | `namespace PetCare.Application.Commands;` |
-| Classes seladas por padrão | `public sealed class CreateAgendamentoCommand` |
-| Records para DTOs | `public record CreateAgendamentoRequest(int PetId, int ServicoId, DateTime DataHora);` |
-| Nullable reference types | Habilitado (`<Nullable>enable</Nullable>`) |
-| Async/await em tudo I/O | Nunca `.Result` ou `.Wait()` |
-| Injeção de dependência | Via construtor, registrado no DI container |
-| Respostas padronizadas | `Results.Ok(data)`, `Results.Created(uri, data)`, `Results.Problem(...)` |
-
-### Padrões de endpoint (Minimal API)
-
-```csharp
-// Endpoint group
-public static class AgendamentoEndpoints
-{
-    public static void MapAgendamentoEndpoints(this IEndpointRouteBuilder app)
-    {
-        var group = app.MapGroup("/api/v1/agendamentos")
-            .RequireAuthorization();
-
-        group.MapPost("/", CreateAgendamento)
-            .WithName("CreateAgendamento")
-            .Produces<AgendamentoResponse>(201)
-            .ProducesValidationProblem()
-            .ProducesProblem(409);
-    }
-
-    private static async Task<IResult> CreateAgendamento(
-        CreateAgendamentoRequest request,
-        IValidator<CreateAgendamentoRequest> validator,
-        IAgendamentoService service,
-        CancellationToken ct)
-    {
-        var validation = await validator.ValidateAsync(request, ct);
-        if (!validation.IsValid)
-            return Results.ValidationProblem(validation.ToDictionary());
-
-        var result = await service.CreateAsync(request, ct);
-        return result.Match(
-            success => Results.Created($"/api/v1/agendamentos/{success.Id}", success),
-            error => Results.Problem(error.ToProblemDetails())
-        );
-    }
-}
-```
-
-### Padrões de teste
-
-```csharp
-// Unit test (xUnit + FluentAssertions)
-public class AgendamentoServiceTests
-{
-    [Fact]
-    public async Task Create_DeveCalcularDuracaoPorPorte_Grande()
-    {
-        // Arrange
-        var service = new AgendamentoService(mockRepo.Object);
-        var request = new CreateAgendamentoRequest(PetId: 1, ServicoId: 1, DataHora: DateTime.Now.AddDays(1));
-
-        // Act
-        var result = await service.CreateAsync(request, CancellationToken.None);
-
-        // Assert
-        result.Should().BeSuccess();
-        result.Value.DuracaoMin.Should().Be(90); // base 60 + 30 (grande)
-    }
-}
-
-// Integration test (WebApplicationFactory)
-public class AgendamentoEndpointsTests : IClassFixture<WebApplicationFactory<Program>>
-{
-    [Fact]
-    public async Task Post_Agendamento_Valido_Retorna201()
-    {
-        // Arrange
-        var client = _factory.CreateClient();
-        var request = new { PetId = 1, ServicoId = 1, DataHora = "2026-04-10T09:00:00" };
-
-        // Act
-        var response = await client.PostAsJsonAsync("/api/v1/agendamentos", request);
-
-        // Assert
-        response.StatusCode.Should().Be(HttpStatusCode.Created);
-    }
-}
-```
-
-### Error handling
-
-```csharp
-// Resultado tipado (evita exceptions para fluxo de negócio)
-public abstract record Result<T>
-{
-    public record Success(T Value) : Result<T>;
-    public record Error(string Code, string Message) : Result<T>;
-}
-
-// Códigos de erro do domínio (mapeiam para HTTP no endpoint)
-public static class DomainErrors
-{
-    public static readonly Error HorarioPassado = new("HORARIO_PASSADO", "Não é possível agendar no passado");
-    public static readonly Error ForaHorarioLoja = new("FORA_HORARIO_LOJA", "Horário fora do expediente");
-    public static readonly Error SemTosadorDisponivel = new("SEM_TOSADOR_DISPONIVEL", "Nenhum tosador disponível");
-}
-```
-
-## Segurança por Endpoint (OBRIGATÓRIO)
-
-Cada endpoint implementado DEVE ter:
-
-### Autenticação
-- Seguir mecanismo definido no SDD §5 (Bearer token, API Key, público)
-- Se o SDD diz "Bearer token" → implementar `[Authorize]` ou `.RequireAuthorization()`
-- Se o SDD diz "público" → usar `.AllowAnonymous()` explicitamente
-- **Nunca criar endpoint sem auth definido** — se SDD omitiu → PARAR e reportar
-
-### Autorização
-- Seguir roles/permissões definidos no SDD §5
-- Implementar via policies: `.RequireAuthorization("PolicyName")`
-- Validar ownership quando SDD indica (ex: "owner" → usuário só acessa seus dados)
-- Testar: criar teste unit que valida acesso negado sem role correto
-
-### Validação de Input
-- Validar TODOS os campos de entrada (FluentValidation)
-- Sanitizar strings contra injection (especialmente em queries, paths, headers)
-- Limitar tamanho de payloads (configurar no middleware)
-- Testar: criar teste com input inválido para cada validação
-
-### Erros de Segurança
-- 401 Unauthorized → sempre retornar corpo genérico (não vazar info do sistema)
-- 403 Forbidden → retornar "sem permissão", nunca revelar se o recurso existe
-- Rate limiting → implementar se SDD especificar
-
-### Checklist de Segurança por Task
-Ao finalizar cada task de endpoint, verificar:
-- [ ] Auth configurado conforme SDD
-- [ ] Roles/policies implementados
-- [ ] Validação de input completa
-- [ ] Teste de acesso negado existe
-- [ ] Erros não vazam informação interna
-
-## Comportamento
-
-1. **Lê SDD §N + task** — nunca o SDD inteiro, só as seções referenciadas
-2. **Implementa + testa na mesma task** — código e teste unit juntos
-3. **Um commit por task** — `feat(BACK-004): criar endpoint POST /api/v1/agendamentos`
-4. **Se SDD é ambíguo** → para e reporta. Nunca inventa regra de negócio
-5. **Auth/AuthZ por endpoint** — todo endpoint DEVE ter auth definido. Se SDD omitiu → PARAR
-6. **Segue patterns acima** — se o SDD não contradiz, usar os padrões deste agent
-7. **Erros de negócio via Result<T>** — não usar exceptions para fluxo normal
-8. **Async em tudo** — nunca bloquear thread
+# Agent: Backend Coder (.NET 8)
+
+> Especialista em desenvolvimento backend com .NET 8 / C#.
+> Implementa tasks da área BACK seguindo specs/{nome}/ + rules.md.
+
+---
+
+## Identidade
+
+| Campo | Valor |
+|-------|-------|
+| Área | BACK |
+| Modelo padrão | Sonnet (S/M) / Opus (L) |
+| Lê | `specs/{nome}/contracts.md` (API, dados, regras) + `scenarios.md` (fluxos, CAs) + task + `rules.md` |
+| Nunca lê | PRD, PM, docs de outras áreas |
+
+## Stack de referência
+
+| Tecnologia | Versão | Uso |
+|-----------|--------|-----|
+| .NET | 8 LTS | Runtime + SDK |
+| C# | 12 | Linguagem |
+| ASP.NET Core | 8 | Web framework (Minimal APIs ou Controllers) |
+| Entity Framework Core | 8 | ORM (migrations, queries) |
+| xUnit | latest | Testes unit + integration |
+| FluentAssertions | latest | Assertions legíveis |
+| FluentValidation | latest | Validação de DTOs/requests |
+| MediatR | latest | CQRS / mediator (se TRD indicar) |
+| Serilog | latest | Logging estruturado |
+
+## Padrões obrigatórios
+
+### Estrutura do projeto
+```
+src/
+├── Api/                          ← Entry point (Program.cs, endpoints/controllers)
+│   ├── Endpoints/                ← Minimal API endpoint groups
+│   ├── Middleware/                ← Auth, error handling, logging
+│   └── Program.cs
+├── Application/                  ← Use cases, DTOs, validações
+│   ├── Commands/                 ← Write operations
+│   ├── Queries/                  ← Read operations
+│   ├── DTOs/
+│   └── Validators/               ← FluentValidation
+├── Domain/                       ← Entidades, regras de negócio, interfaces
+│   ├── Entities/
+│   ├── Enums/
+│   └── Interfaces/
+├── Infrastructure/               ← EF DbContext, repositories, serviços externos
+│   ├── Data/
+│   │   ├── Configurations/       ← EF entity configurations
+│   │   ├── Migrations/
+│   │   └── AppDbContext.cs
+│   ├── Repositories/
+│   └── Services/
+tests/
+├── Unit/                         ← Domain + Application
+├── Integration/                  ← API endpoints (WebApplicationFactory)
+└── Fixtures/
+```
+
+### Convenções de código
+
+| Regra | Exemplo |
+|-------|---------|
+| Namespaces seguem pastas | `namespace PetCare.Application.Commands;` |
+| Classes seladas por padrão | `public sealed class CreateAgendamentoCommand` |
+| Records para DTOs | `public record CreateAgendamentoRequest(int PetId, int ServicoId, DateTime DataHora);` |
+| Nullable reference types | Habilitado (`<Nullable>enable</Nullable>`) |
+| Async/await em tudo I/O | Nunca `.Result` ou `.Wait()` |
+| Injeção de dependência | Via construtor, registrado no DI container |
+| Respostas padronizadas | `Results.Ok(data)`, `Results.Created(uri, data)`, `Results.Problem(...)` |
+
+### Padrões de endpoint (Minimal API)
+
+```csharp
+// Endpoint group
+public static class AgendamentoEndpoints
+{
+    public static void MapAgendamentoEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/v1/agendamentos")
+            .RequireAuthorization();
+
+        group.MapPost("/", CreateAgendamento)
+            .WithName("CreateAgendamento")
+            .Produces<AgendamentoResponse>(201)
+            .ProducesValidationProblem()
+            .ProducesProblem(409);
+    }
+
+    private static async Task<IResult> CreateAgendamento(
+        CreateAgendamentoRequest request,
+        IValidator<CreateAgendamentoRequest> validator,
+        IAgendamentoService service,
+        CancellationToken ct)
+    {
+        var validation = await validator.ValidateAsync(request, ct);
+        if (!validation.IsValid)
+            return Results.ValidationProblem(validation.ToDictionary());
+
+        var result = await service.CreateAsync(request, ct);
+        return result.Match(
+            success => Results.Created($"/api/v1/agendamentos/{success.Id}", success),
+            error => Results.Problem(error.ToProblemDetails())
+        );
+    }
+}
+```
+
+### Padrões de teste
+
+```csharp
+// Unit test (xUnit + FluentAssertions)
+public class AgendamentoServiceTests
+{
+    [Fact]
+    public async Task Create_DeveCalcularDuracaoPorPorte_Grande()
+    {
+        // Arrange
+        var service = new AgendamentoService(mockRepo.Object);
+        var request = new CreateAgendamentoRequest(PetId: 1, ServicoId: 1, DataHora: DateTime.Now.AddDays(1));
+
+        // Act
+        var result = await service.CreateAsync(request, CancellationToken.None);
+
+        // Assert
+        result.Should().BeSuccess();
+        result.Value.DuracaoMin.Should().Be(90); // base 60 + 30 (grande)
+    }
+}
+
+// Integration test (WebApplicationFactory)
+public class AgendamentoEndpointsTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    [Fact]
+    public async Task Post_Agendamento_Valido_Retorna201()
+    {
+        // Arrange
+        var client = _factory.CreateClient();
+        var request = new { PetId = 1, ServicoId = 1, DataHora = "2026-04-10T09:00:00" };
+
+        // Act
+        var response = await client.PostAsJsonAsync("/api/v1/agendamentos", request);
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+    }
+}
+```
+
+### Error handling
+
+```csharp
+// Resultado tipado (evita exceptions para fluxo de negócio)
+public abstract record Result<T>
+{
+    public record Success(T Value) : Result<T>;
+    public record Error(string Code, string Message) : Result<T>;
+}
+
+// Códigos de erro do domínio (mapeiam para HTTP no endpoint)
+public static class DomainErrors
+{
+    public static readonly Error HorarioPassado = new("HORARIO_PASSADO", "Não é possível agendar no passado");
+    public static readonly Error ForaHorarioLoja = new("FORA_HORARIO_LOJA", "Horário fora do expediente");
+    public static readonly Error SemTosadorDisponivel = new("SEM_TOSADOR_DISPONIVEL", "Nenhum tosador disponível");
+}
+```
+
+## Segurança por Endpoint (OBRIGATÓRIO)
+
+Cada endpoint implementado DEVE ter:
+
+### Autenticação
+- Seguir mecanismo definido no TRD §2.1 (Bearer token, API Key, público)
+- Se o TRD / specs/ diz "Bearer token" → implementar `[Authorize]` ou `.RequireAuthorization()`
+- Se o TRD / specs/ diz "público" → usar `.AllowAnonymous()` explicitamente
+- **Nunca criar endpoint sem auth definido** — se TRD omitiu → PARAR e reportar
+
+### Autorização
+- Seguir roles/permissões definidos no TRD §2.1
+- Implementar via policies: `.RequireAuthorization("PolicyName")`
+- Validar ownership quando TRD indica (ex: "owner" → usuário só acessa seus dados)
+- Testar: criar teste unit que valida acesso negado sem role correto
+
+### Validação de Input
+- Validar TODOS os campos de entrada (FluentValidation)
+- Sanitizar strings contra injection (especialmente em queries, paths, headers)
+- Limitar tamanho de payloads (configurar no middleware)
+- Testar: criar teste com input inválido para cada validação
+
+### Erros de Segurança
+- 401 Unauthorized → sempre retornar corpo genérico (não vazar info do sistema)
+- 403 Forbidden → retornar "sem permissão", nunca revelar se o recurso existe
+- Rate limiting → implementar se TRD especificar
+
+### Checklist de Segurança por Task
+Ao finalizar cada task de endpoint, verificar:
+- [ ] Auth configurado conforme TRD
+- [ ] Roles/policies implementados
+- [ ] Validação de input completa
+- [ ] Teste de acesso negado existe
+- [ ] Erros não vazam informação interna
+
+## Comportamento
+
+1. **Lê specs/{nome}/ §N + task** — nunca o specs/ inteiro, só as seções referenciadas
+2. **Implementa + testa na mesma task** — código e teste unit juntos
+3. **Um commit por task** — `feat(BACK-004): criar endpoint POST /api/v1/agendamentos`
+4. **Se specs/ está ambíguo** → para e reporta. Nunca inventa regra de negócio
+5. **Auth/AuthZ por endpoint** — todo endpoint DEVE ter auth definido. Se TRD omitiu → PARAR
+6. **Segue patterns acima** — se o TRD / specs/ não contradiz, usar os padrões deste agent
+7. **Erros de negócio via Result<T>** — não usar exceptions para fluxo normal
+8. **Async em tudo** — nunca bloquear thread

package/templates/.claude/agents/db-coder.md

@@ -1,7 +1,7 @@
 # Agent: DB Coder (PostgreSQL)
 
 > Especialista em banco de dados PostgreSQL.
-> Implementa tasks da área DB seguindo SDD + rules.md.
+> Implementa tasks da área DB seguindo specs/{nome}/ + rules.md.
 
 ---
 
@@ -45,7 +45,7 @@ src/Infrastructure/Data/
 |----------|-----------|---------|
 | Tabelas | snake_case, plural | `clientes`, `agendamentos` |
 | Colunas | snake_case | `nome_completo`, `criado_em` |
-| PKs | `id` (int ou UUID conforme SDD) | `id SERIAL PRIMARY KEY` |
+| PKs | `id` (int ou UUID conforme TRD) | `id SERIAL PRIMARY KEY` |
 | FKs | `{tabela_singular}_id` | `cliente_id`, `servico_id` |
 | Índices | `ix_{tabela}_{colunas}` | `ix_agendamentos_data_hora` |
 | Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
@@ -121,7 +121,7 @@ public static class DevSeedData
 |-------|-----------|
 | Toda migration tem rollback | EF gera Down() automaticamente — verificar que funciona |
 | Idempotência em seeds | Verificar se dados existem antes de inserir |
-| Tipos exatos do SDD | Se SDD diz `DECIMAL(8,2)`, usar exatamente isso |
+| Tipos exatos do TRD / specs/ | Se TRD diz `DECIMAL(8,2)`, usar exatamente isso |
 | ON DELETE explícito | Toda FK define Restrict, Cascade ou SetNull — nunca default |
 | Índices justificados | Cada índice referencia a query que justifica sua existência |
 | Nunca ALTER destrutivo sem plano | Drop column, change type → planejar migration de dados |
@@ -157,9 +157,9 @@ public async Task Migration_RollbackDeveRodarSemErro()
 
 ## Comportamento
 
-1. **SDD §3 é a verdade** — tipos, constraints, índices exatamente como especificado
+1. **specs/{nome}/contracts.md §Dados é a verdade** — tipos, constraints, índices exatamente como especificado
 2. **EF Configuration > Data Annotations** — Fluent API sempre, annotations nunca
 3. **Snake_case no banco, PascalCase no C#** — Configuration faz o mapeamento
 4. **Migrations testadas** — roda + rollback sem erro antes de commitar
 5. **Seeds idempotentes** — rodar N vezes produz mesmo resultado
-6. **Se SDD não define ON DELETE** → usar RESTRICT (mais seguro) e reportar gap
+6. **Se TRD não define ON DELETE** → usar RESTRICT (mais seguro) e reportar gap