specd-propose

Segundo passo do ciclo. Transforma explore/notes.md em delta.md. Não toca no código e não escreve em .specd/specs/.

Antes de qualquer coisa

specd --version

Menor que requires_specd → pare, nomeando a instalada e a exigida.

1. Ler a exploração

explore/notes.md da change. Se o código mudou desde que ele foi escrito, o explore está vencido: volte para specd-explore antes de propor. Explore vencido é a forma mais barata de produzir proposta ancorada em símbolo que já não existe.

2. Ler a spec efetiva

specd spec --json

É daqui que sai o que já existe. Nunca reconstrua o overlay lendo .specd/specs/ e os deltas soltos.

Todo REQ-ID citado é conferido nesta saída antes de entrar em qualquer texto.

3. Escrever o delta

.specd/changes/<nome>/delta.md:

---
change: 2026-08-01-escopo
target: [capability-a, capability-b]
---

## ADDED

### REQ-XXX-001 — Título curto

**Capability.** capability-a

**Statement.** The specd <sujeito> SHALL <comportamento>.

**Acceptance.**

- critério verificável
- outro critério verificável

Prosa explicando por que, e o que foi medido. Não é decoração: é o que impede
a próxima pessoa de desfazer a decisão sem saber que existiu.

```yaml anchors
- file: src/modulo/arquivo.ts
  symbol: "export function nome"
```

Regras que o gate cobra:

• Um SHALL por statement. Dois comportamentos são dois requisitos.
• EARS: ubiquitous, event-driven (WHEN), state-driven (WHILE), unwanted-behaviour (IF … THEN), optional-feature (WHERE).
• ADDED declara **Capability.**; MODIFIED pode omitir — o destino é a capability que já contém o ID.
• MODIFIED carrega o texto completo, não um patch.
• REMOVED aceita só a lista de identificadores.
• Identificador aposentado nunca é reusado.
• A âncora é file obrigatório e symbol opcional, e o símbolo é procurado literalmente: export async function f e export function f são strings diferentes.

Âncora pode apontar para símbolo que ainda não existe. Com origin: delta isso é warning, e é esse afrouxamento que torna possível propor antes de implementar.

Revisar cada statement antes de seguir

Três perguntas mecânicas, por requisito escrito. Corrigir aqui é gratuito: o requisito ainda é origin: delta, nenhuma task o cita, nenhuma âncora tem histórico. Depois do archive o mesmo conserto é change própria com MODIFIED.

1. Um assunto? Um SHALL por statement — o gate já cobra isso. E nenhum critério de aceite descrevendo comportamento que o statement não menciona: "sai 0 sempre que consegue ler" com um critério sobre requisição de rede são dois requisitos escritos como um.
2. A quantificação cabe no alcance da âncora? Statement que diz "toda skill" com âncora num arquivo de skill afirma quatro coisas e verifica uma — apagar as outras três não move o gate. Ou a âncora cobre o que o statement quantifica, ou o statement fala do que a âncora alcança.

3. Todo critério tem teste possível? Não o teste escrito — o teste que dá para escrever. Critério que ninguém consegue verificar é prosa com marcador.

   Requisito sobre comportamento de skill é a exceção declarada: nenhuma asserção verifica que uma skill faz três perguntas, porque quem executa é um agente lendo markdown. Nesses, o teste possível é sobre o texto do SKILL.md — verificação fraca e honesta. É a mesma razão que põe o comportamento numa skill e não no CLI: julgamento no caminho de decisão é o que no-llm-in-decision-path proíbe. Aponte a exceção; não reprove o requisito por ser o que é.

O que essas três não resolverem vai ao autor pela ferramenta de pergunta do host, com as opções concretas. A skill aponta; ela não reescreve enunciado por conta própria, e não decide sozinha o que é bom enunciado.

Uma pergunta que não cabe aqui: "a âncora realiza o comportamento?". No propose o símbolo pode não existir, e perguntar produziria resposta inventada. Ela é da specd-archive-change.

4. Escrever as tasks

tasks/NNN-nome.md, uma por unidade de trabalho:

---
id: "001-nome"
change: 2026-08-01-escopo
req: [REQ-XXX-001]
status: pending
evidence:
  commits: []
---

Todo requisito do delta precisa de pelo menos uma task que o cite, ou a camada coverage reprova.

5. Conferir

specd verify --fast

Verde com warnings de âncora é o estado esperado de uma proposta: os símbolos ainda não existem. Vermelho é problema de formato, e volta para o passo 3.

Gravar o registro do propose

specd propose-record --change <nome>

Depois do passo 4: o comando recusa change que declara requisito e não tem task, porque ausência de task não prova que a implementação não começou. O comando grava propose.json no diretório da change com, por requisito que a change declara, o statement, os critérios, as âncoras e se cada uma resolve neste instante — resolvendo cada âncora, não lendo relatório de camada.

Rode sempre, inclusive quando o delta só remove requisito: o registro vazio que resulta é o marco daquela change, e specd archive recusa change sem marco. Change que abre só com REMOVED pode ganhar requisito durante o apply, e sem o registro ela chegaria ao archive declarando requisito, sem marco e sem poder mais gravar um.

Não monte esse arquivo à mão e não copie campo de saída nenhuma. Erro de transcrição em resolved produz recorte vazio na specd-archive-change, que é a direção perigosa: a revisão informaria "nada mudou" para uma change onde tudo mudou.

Delta reescrito enquanto toda task está pending regrava o registro: rode o comando de novo. Depois que qualquer task saiu de pending, o comando recusa — rodar de novo depois do apply gravaria o estado pós-apply, e o recorte da revisão sairia vazio pelo mesmo motivo. A recusa é do CLI, não sua: a regra esteve só neste texto e foi furada na primeira vez que alguém teve a chance.

É isto que dá referente ao recorte da specd-archive-change: nada mais no repositório registra que uma âncora esteve pendurada, e sem esse dado a revisão de lá vira leitura de tudo, todo archive.

6. Sincronizar com o board, havendo board

specd sync --dry-run --json

Mostre o plano ao autor antes de escrever qualquer coisa. sync reconcilia a spec efetiva inteira: o plano pode conter itens de outras changes abertas, e isso é dito em voz alta, não escondido.

Peça confirmação explícita pela ferramenta de pergunta do host. Só depois:

specd sync

Escrita em sistema de terceiro é anunciada antes de acontecer (costly-ops-are-not-silent).

Board configurado e inalcançável → pare. Não proponha "seguir sem sincronizar por enquanto" como se fosse equivalente.

Sem board, o passo não existe, e o delta sozinho é a proposta completa — o que o obriga a ser legível também por gente.

Quando parar e perguntar

Use a ferramenta de pergunta do host, com opções, sempre que:

• o requisito proposto contradiz um já realizado
• duas changes abertas tocam o mesmo identificador
• não está claro se é ADDED ou MODIFIED
• a âncora não tem um símbolo honesto para apontar

O delta é contrato. Contrato escrito no chute é pior que contrato ausente.