Mantendo-o atualizado

handbook resync --case <case-dir> --work <workdir>

A documentação apodrece porque atualizá-la custa tanto quanto escrevê-la. O resync torna a atualização proporcional à mudança.

O contrato do case

Um case é um diretório que você monta. Ele responde a duas perguntas: como o código está agora e qual era a mudança pretendida.

cases/upload-retry/
  edited/       the changed source tree             REQUIRED
  plan.md       what the change was                 optional — SHARPENS the scope
  change.diff   unified diff vs the previous tree   optional — WIDENS the scope

mkdir -p cases/upload-retry
cp -R $REPO cases/upload-retry/edited
cp plan.md cases/upload-retry/
git -C $REPO diff HEAD~1 > cases/upload-retry/change.diff

handbook resync --case cases/upload-retry --work work/api

Um change.diff vazio significa "nada a fazer", e a execução é pulada de forma limpa em vez de tratada como "tudo mudou".

O que ele realmente faz

1. Reanalisa a árvore editada — um grafo de phase 1 novo em folha.
2. Compara o antigo com o novo → arquivos alterados / adicionados / excluídos.
3. Regenera as fichas dos arquivos alterados e adicionados.
4. Atribui os arquivos adicionados, descarta os excluídos e reconcilia os buckets.
5. Reconstrói a organização das etapas afetadas — determinístico, sem LLM.
6. Renarra as etapas afetadas e a visão geral do sistema. Graças ao cache por hash de conteúdo, uma etapa não afetada não é renarrada de forma alguma.
7. Atualiza os registradores.
8. Atualiza as saídas já renderizadas sob <work>/handbook (--no-render para pular).

{
  "skipped": false,
  "changedFiles": ["src/upload.py"],
  "addedFiles": [],
  "deletedFiles": [],
  "affectedStages": ["stage-3"],
  "cardsRegenerated": 1,
  "narrated": true,
  "rendered": ["work/api/handbook/overview.md", "work/api/handbook/stage-3.md"]
}

Como o diff captura as mudanças

Os hashes por arquivo foram gravados pela phase 1 exatamente para este propósito. Um grafo anterior a eles recorre à estrutura — degradado, mas nunca errado.

Trabalhando sem um endpoint

handbook resync --case cases/x --work work/api --no-llm

Os fatos estruturais são atualizados — grafo de chamadas, inventário de funções, atribuição, ordenação — e o propósito de cada ficha afetada recebe (stale: code changed since narration) ao final.

Essa é a degradação honesta. A alternativa — deixar a prosa intacta e sem marcação — é um handbook que mente em silêncio.

Realimentando correções

handbook resync --case cases/x --work work/api \
  --corrections skills/api/corrections.jsonl

Os arquivos nomeados em corrections.jsonl entram no conjunto a atualizar mesmo que seus bytes nunca tenham mudado, porque uma afirmação que o código-fonte contradiz é razão suficiente para descrever esse arquivo de novo. Depois, o arquivo consumido é arquivado com um timestamp, de modo que a mesma correção não possa ser aplicada duas vezes.

Linhas malformadas são reportadas em report.corrections.problems e nunca são fatais — uma linha ruim escrita por um agente não deve bloquear a atualização.

Detalhe e idioma ficam como estão

--detail e --narrate-lang ficam indefinidos por padrão, e indefinido significa "corresponder ao que este handbook já é". Um resync nunca rebaixa silenciosamente um handbook deep para brief, nem vira um handbook em chinês para o inglês.

Passe-os explicitamente apenas quando você realmente quiser mudar a profundidade ou o idioma — e espere um handbook misto até que todas as fichas tenham sido regeneradas.

Quando regenerar em vez disso

O resync avança a camada derivada. Regenere quando a estrutura deve mudar:

Automatizando

on:
  push:
    branches: [main]

jobs:
  resync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 2 }
      - run: |
          mkdir -p case
          cp -R . case/edited
          git diff HEAD~1 > case/change.diff
      - run: handbook resync --case case --work work/api
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: handbook validate --skill skills/api --source .

edited/ também pode ser dispensado por completo quando você aciona o resync de forma programática: a opção editedRoot aponta para uma árvore viva em vez disso, que é como o Studio o executa no próprio lugar, sem copiar o repositório.

Segurança

• O mesmo lock de diretório do generate, de modo que um resync nunca pode se intercalar com uma geração concorrente sobre os mesmos artefatos.
• A área de staging da phase 1 é sempre limpa — <case>/.resync-phase1 nunca sobrevive à chamada, com sucesso ou com falha.
• As fichas de arquivos excluídos são removidas, de modo que um arquivo excluído não pode permanecer no handbook.
• Cancelável — um AbortSignal é verificado entre os passos e propagado a cada passada do LLM.