Planejando uma mudança

handbook plan --source <repo> --handbook <dir> --request "<text>" --out plan.md

O planejador é um agente somente leitura. Ele lista, lê e faz grep — não tem ferramenta de escrita alguma, nem mesmo uma desabilitada — e sua saída é um plano para outra coisa executar.

O loop

1. Roteie com o handbook: quais arquivos, funções e estados estão no escopo?
2. Leia o código-fonte real em cada endereço encontrado.
3. Emita blocos ### EDIT n com textos old e new exatos em bytes.
4. Termine com um bloco JSON de declarações.

Escrevendo um bom pedido

Declare o comportamento que você quer, não o arquivo em que você acha que ele está. Nomear um arquivo estreita a busca do planejador ao lugar em que você já tinha pensado — o que anula o propósito.

Lendo o plano

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

### EDIT 2

- file: `src/upload.py`
- where: `Uploader` — add the helper

```old
    def send(self, url, data):
```

```new
    def _retry(self, call, attempts):
        last = None
        for _ in range(attempts):
            try:
                return call()
            except TransientError as exc:
                last = exc
        raise last

    def send(self, url, data):
```

Both call sites now share one retry policy.

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

Regras que o formato obedece:

• old deve ser exato em bytes e aparecer exatamente uma vez no arquivo.
• Um old vazio significa "crie este arquivo".
• As edições são numeradas e ascendem, de cima para baixo.
• O bloco json final é consumido pelo resync para afinar seu escopo de atualização.

Leia o plano antes de aplicá-lo. O dry run diz se ele aplicaria; só você pode dizer se ele deveria.

Quando ele desiste

plan sai com código diferente de zero — ele não escreve um pedido de desculpas no plan.md para um script alimentar o apply.

Ajustando

Sem um handbook

handbook plan --source ~/code/api --request "…"

Funciona — o planejador recua para explorar o código-fonte diretamente — mas este é o modo degradado. O handbook existe precisamente porque a exploração sem guia encontra os pontos óbvios e perde os espalhados.

O que o sandbox permite

list_dir(path)
read_file(path, start_line?, end_line?)
grep(pattern, path)
finish(plan)

• Todo caminho é resolvido dentro da raiz do sandbox; escapes, inclusive por symlinks, são rejeitados.
• O handbook é montado como somente leitura em __handbook__/, um sandbox separado do código-fonte.
• Leituras têm teto de 60.000 caracteres; o grep tem teto de 100 ocorrências e pula arquivos com mais de 5 MB.
• Regexes catastróficas — um quantificador sem limite sobre um grupo que contém outro, como (a+)+ ou (.*)* — são recusadas com um erro de ferramenta gracioso em vez de travar a execução.

A seguir