# 02-prd.md — SDDL-3: Fix correção run SDD validation

**Artefato**: PRD (Etapa 2)
**Card**: SDDL-3
**Data**: 2026-06-24
**Rastreabilidade**: `docs/sddl-3/02-prd.md`
**Origem**: `docs/sddl-3/01-idea.md`

---

## 1. Rastreabilidade

| Campo | Valor |
|---|---|
| Card | SDDL-3 |
| Ideia | `docs/sddl-3/01-idea.md` |
| Discovery | `docs/sddl-3/00-project-discovery.md` |
| Próximo artefato | `docs/sddl-3/03-techspec.md` |

---

## 2. Resumo executivo

O CI do `sdd-layer` falha após bumps de versão porque `VERSION`, `Cargo.toml` e `Cargo.lock` são atualizados manualmente em etapas separadas. A função `version_alignment_issues` trata qualquer divergência como FAILURE (`strict_contract=true`). O fix entrega um script de bump atômico que sincroniza os três arquivos em uma única invocação.

---

## 3. Não objetivos

- Integrar ao binário `sdd` como `sdd bump`
- Criar tag Git ou release GitHub automaticamente
- Alterar lógica de `version_alignment_issues` em `src/main.rs`
- Modificar os workflows de CI existentes
- Changelog automático ou confirmação interativa

---

## 4. Requisitos funcionais

| ID | Requisito |
|---|---|
| RF-01 | O script aceita versão semver explícita (ex.: `0.16.0`) ou tipo de incremento (`patch`, `minor`, `major`) |
| RF-02 | O script atualiza o campo `version` na seção `[package]` de `Cargo.toml` |
| RF-03 | O script executa `cargo update -p sdd` para regenerar `Cargo.lock` |
| RF-04 | O script escreve a versão alvo em `VERSION` na raiz |
| RF-05 | O script imprime as versões resultantes nos três arquivos ao final |
| RF-06 | O script retorna exit code `0` em sucesso e não-zero em falha |
| RF-07 | O script aborta e reporta erro se `cargo update` falhar, sem deixar arquivos inconsistentes |

---

## 5. Requisitos não-funcionais

| ID | Requisito |
|---|---|
| RNF-01 | **Atomicidade**: falha em qualquer etapa não deixa os três arquivos dessincronizados |
| RNF-02 | **Idempotência**: re-execução com mesmo argumento produz mesmo estado sem erros |
| RNF-03 | **Portabilidade**: funciona em `ubuntu-latest` (bash) e Windows 11 (PowerShell) sem dependências além de `cargo` |
| RNF-04 | **Sem efeitos em Git**: não cria commits, tags ou branches |

---

## 6. Regras de negócio

| ID | Regra |
|---|---|
| RN-01 | Os três arquivos devem sempre conter a mesma versão ao final de qualquer bump |
| RN-02 | A versão alvo deve ser semver válido (`MAJOR.MINOR.PATCH`) |
| RN-03 | O script é a única forma suportada de bump; bumps manuais são não conformes |
| RN-04 | O script deve residir em `scripts/` e ser documentado |

---

## 7. Critérios de aceite

```gherkin
Feature: Bump atômico de versão no sdd-layer

  Background:
    Given o repositório sdd-layer está com todos os arquivos em versão "0.15.2"
    And o script de bump está disponível em "scripts/bump-version"

  Scenario: Bump com versão explícita
    When o mantenedor executa o script com argumento "0.16.0"
    Then o campo "version" em "Cargo.toml" deve ser "0.16.0"
    And a entrada "sdd-layer" em "Cargo.lock" deve ser "0.16.0"
    And o conteúdo de "VERSION" deve ser "0.16.0"
    And o script deve retornar exit code 0

  Scenario: Bump com incremento patch
    When o mantenedor executa o script com argumento "patch"
    Then a versão resultante nos três arquivos deve ser "0.15.3"
    And o script deve retornar exit code 0

  Scenario: Idempotência
    Given o repositório já está com versão "0.16.0" nos três arquivos
    When o mantenedor executa o script novamente com argumento "0.16.0"
    Then os três arquivos permanecem com versão "0.16.0"
    And o script retorna exit code 0 sem mensagem de erro

  Scenario: Argumento inválido
    When o mantenedor executa o script com argumento "abc"
    Then o script deve retornar exit code não-zero
    And nenhum arquivo deve ser modificado

  Scenario: CI verde após bump
    Given o script foi executado com sucesso para "0.16.0"
    When o workflow "sdd-layer.yml" executa "sdd ci"
    Then "version_alignment_issues" deve retornar zero issues
    And o step "sdd ci" deve concluir com sucesso
```

---

## 8. Escopo MVP

**Dentro**: `scripts/bump-version.sh` e `scripts/bump-version.ps1`, atualização atômica dos três arquivos, exit codes corretos, documentação mínima no script.

**Fora**: `sdd bump` integrado, commit/tag automático, confirmação interativa, CHANGELOG, workspaces Cargo.

---

## 9. Pontos para a Tech Spec resolver

1. Script único multiplataforma vs dois scripts separados (`.sh` + `.ps1`)
2. Mecanismo de substituição de texto em `Cargo.toml` em Windows (sem `sed` nativo)
3. Verificar comportamento de `cargo update -p sdd` — atualiza apenas `sdd-layer` ou há efeitos colaterais
