sdd-layer 0.15.3

# Artifact store local

O artifact store local é o fallback mínimo da pipeline SDD. Ele garante que cada etapa tenha um artefato recuperável dentro do próprio projeto, mesmo quando Jira, Confluence, Bitbucket, GitHub, GitLab, Linear ou Notion ainda não estão configurados por completo.

## Convenção

Cada orquestração usa um diretório próprio:

```text
docs/<slug-da-orquestracao>/
```

Inicialize com:

```bash
sdd init "<nome-da-orquestracao>"
```

Sem argumento, `sdd init` inicializa a camada SDD no projeto atual. Com argumento, ele cria o artifact store da orquestração.

Exemplo:

```bash
sdd init "exportacao csv relatorio vendas"
```

Isso cria:

```text
docs/exportacao-csv-relatorio-vendas/
├── README.md
└── traceability-map.yaml
```

O `traceability-map.yaml` é a fonte local de verdade para estado dos artefatos, ponteiros externos e relação entre etapas. Logs em `.sdd/*.jsonl` são observabilidade derivada; não substituem o mapa.

## Arquivos por etapa

| Etapa | Stage | Arquivo |
|---|---|---|
| Project Discovery | `project-discovery` | `00-project-discovery.md` |
| Risk Classification | `risk` | `00-risk-classification.md` |
| Ideia | `idea` | `01-idea.md` |
| PRD | `prd` | `02-prd.md` |
| Tech Spec | `techspec` | `03-techspec.md` |
| Tasks | `tasks` | `04-tasks.md` |
| Refinement | `refinement` | `05-refinement.md` |
| Execution | `execution` | `06-execution.md` |
| ADR | `adr` | `06-adr.md` |
| Review | `review` | `07-review.md` |
| Memory | `memory` | `08-memory.md` |

## Quando salvar

Salve etapas informativas como `recorded`:

```bash
sdd artifact save "<nome-da-orquestracao>" idea --file idea.md --state recorded
```

Salve etapas com checkpoint humano somente depois de aprovação explícita:

```bash
sdd artifact save "<nome-da-orquestracao>" prd --file prd.md --state approved
sdd artifact save "<nome-da-orquestracao>" techspec --file techspec.md --state approved
sdd artifact save "<nome-da-orquestracao>" review --file review.md --state approved
```

Para substituir uma versão após ajustes aprovados:

```bash
sdd artifact save "<nome-da-orquestracao>" prd --file prd.md --state approved --force
```

Para acumular várias tasks de execução no mesmo arquivo:

```bash
sdd artifact save "<nome-da-orquestracao>" execution --file execution-task-003.md --state recorded --append
```

## Ver status

```bash
sdd artifact status "<nome-da-orquestracao>"
sdd eval orchestration --name "<nome-da-orquestracao>" --json
sdd quality report --name "<nome-da-orquestracao>" --json
```

O comando mostra quais arquivos já existem e quais ainda faltam.

## Logs relacionados

| Arquivo | Papel |
|---|---|
| `.sdd/evaluations.jsonl` | avaliações de stage/orquestração e quality reports |
| `.sdd/runs.jsonl` | runs de comandos e stages |
| `.sdd/events.jsonl` | timeline normalizada de geração/execução |
| `.sdd/execution-runs.jsonl` | execução task-by-task, tentativas, evidências e testes |
| `.sdd/state/<slug>.json` | estado durável do motor autônomo, lock, cursor, tasks e `last_error` |
| `.sdd/workflows/<workflow-id>.json` | último relatório durável de `sdd workflow run` |
| `.sdd/workflows.jsonl` | eventos append-only de nodes `command` em workflows |

Esses arquivos devem ser append-only quando forem logs. Se precisarem expor erro de provider, comando ou payload, grave a versão redigida.

## Workflows e artifact store

`sdd workflow run standard-sdd --input "<feature>"` usa a mesma fila de demandas, estado durável e artifact store do motor autônomo. O workflow pode criar artefatos em `docs/<slug>/`, pausar em gates e persistir o relatório em `.sdd/workflows/standard-sdd.json`.

Workflows não substituem `traceability-map.yaml`; eles apenas registram o que foi executado, produzido, pausado ou bloqueado. A aprovação de PRD, Tech Spec, Refinement, merge, release e deploy continua sendo uma decisão humana explícita.

## Relação com integrações externas

O store local não substitui Jira, Confluence ou o Git provider quando eles existem. Ele é a linha de base:

- se Confluence existe, salve o link externo no `traceability-map.yaml` e mantenha o arquivo local como fallback;
- se Jira existe, use Jira para estado/workflow e o arquivo local para evidência mínima;
- se não há integração externa confiável, `docs/<slug-da-orquestracao>/` é a fonte canônica da orquestração.

Mesmo com integração externa completa, o store local deve ter ponteiros suficientes para `sdd eval`, `sdd quality report`, `sdd trace summary` e `sdd auto run` reconstruírem o estado sem depender de memória da conversa.