Disciplina de planos — Memória de trabalho efêmera e local ao projeto

Referência normativa canônica para colaboradores posteriores. Este documento espelha a seção de Disciplina de planos da especificação do projeto (Especificação §3); é a referência independente que acompanha o repositório publicado. A disciplina introduzida aqui é fundamental; cada diretiva abaixo é um MUST (DEVE), salvo marcação explícita em contrário. A justificativa arquitetural está registrada em ADR-0001.

1. Definição e limitesCopy Anchor Link

Um plano é qualquer artefato de trabalho deliberado e transitório produzido durante o raciocínio sobre um projeto, incluindo mas não se limitando a:

• Esboços de arquitetura, percursos de projeto de sistema, decomposições de componentes.
• Estruturas analíticas de trabalho, listas de tarefas de várias etapas, árvores de decomposição.
• Estratégias de refatoração, percursos de migração, sequências de implantação.
• Diários de depuração, registros de hipóteses, notas de reprodução.
• Notas de exploração, resumos de spike, rascunhos de prompt, transcrições do harness mantidas para uso posterior.
• Qualquer documento escrito para pensar com ele, não para entregar.

Os planos são categoricamente distintos destas classes adjacentes:

Os planos precedem os ADRs. Quando um plano converge para uma decisão duradoura, a decisão é promovida a um ADR (§4 Ciclo de vida); o plano em si é arquivado ou descartado.

2. Localização, visibilidade e nomenclaturaCopy Anchor Link

• Caminho. <project-root>/.apothem/plans/ é o único lar canônico. Uma árvore legada <project-root>/.plans/ não é mais canônica — atualize-a com apothem migrate-workspace (§5). Não um diretório de configuração do harness (por exemplo ~/.claude/plans/, ~/.claude/.plans/ ou ~/.codex/.plans/). Não uma pasta de rascunhos da área de trabalho. Não ~/notes/. Não tmp/plans/.
• Visibilidade. A pasta é registrada no .gitignore do projeto conforme o trecho canônico de §6. O ambiente de execução do harness DEVE verificar que esta entrada esteja presente antes de qualquer escrita; se ausente, ele anexa a entrada com um comentário de cabeçalho de uma linha e o link para este documento.
• Convenção de nome de arquivo. YYYY-MM-DD--<kebab-case-slug>.md. Para espaços de trabalho maiores, subcategorize em .apothem/plans/<area>/YYYY-MM-DD--<slug>.md.
  • Exemplos: .apothem/plans/2026-04-30--auth-refactor-strategy.md, .apothem/plans/api/2026-04-30--rate-limit-rollout.md.
• Índice. Um .apothem/plans/INDEX.md opcional (também gitignored) pode agregar links e status; se presente, o ambiente de execução do harness o mantém a cada escrita de plano.
• Arquivamento. Planos convergidos ou abandonados são realocados para .apothem/plans/_archive/. Nunca excluídos sem confirmação explícita por consulta estruturada.
• Cabeçalho de autoria nos planos. Os planos estão isentos da linha SPDX do cabeçalho de autoria (conforme site/content/docs/reference/authorship-header.mdx §Lista de exceções). São efêmeros gitignored; aplicar um marcador de procedência permanente à memória de trabalho transitória é um erro de categoria. O frontmatter (§3) carrega a procedência do plano.

3. Esquema de frontmatter (validado)Copy Anchor Link

Todo arquivo de plano carrega:

---
title: <human-readable title>
project: <git-remote-url-or-canonical-local-path>
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
status: draft | in-progress | converged | abandoned
tags: [<kebab>, ...]
supersedes: <prior-plan-relative-path or null>
promotes-to: <ADR path or null>
---

Um JSON Schema para os planos vive em src/apothem/schemas/plan.schema.json. O comando de barra /plan (e o validador plans-discipline-language) valida contra ele a cada escrita.

4. Ciclo de vida e fluxo de promoçãoCopy Anchor Link

1. Rascunho (Draft) — criação inicial; status: draft.
2. Em andamento (In-progress) — iterado ativamente; status: in-progress; updated atualizado a cada edição material.
3. Convergência (Convergence) — uma decisão duradoura cristaliza:
   1. Extraia a decisão para um novo ADR na localização de ADR ratificada pelo projeto.
   2. Defina o promotes-to do plano para o caminho do ADR.
   3. Defina status: converged.
   4. Opcionalmente mova para .apothem/plans/_archive/.
4. Abandono (Abandonment) — direção abandonada; status: abandoned; arquive ou, com consulta estruturada explícita, descarte.
5. Substituição (Supersession) — quando um novo plano substitui um mais antigo, defina o supersedes do novo plano para o caminho do plano antigo, e defina o status do plano antigo de acordo.

A promoção é o único caminho pelo qual o conteúdo de um plano se torna duradouro, versionado e visível para os colegas de equipe. Nenhum plano jamais migra integralmente para o código-fonte versionado.

5. Protocolo de migração — Única, de um diretório de planos do harness para um .apothem/plans/ por projetoCopy Anchor Link

Nota. Este protocolo se aplica a projetos posteriores que adotam a Disciplina de planos pela primeira vez, onde os artefatos de planejamento anteriores vivem dentro de um diretório de configuração do harness (por exemplo ~/.claude/plans/, ~/.claude/.plans/ ou o caminho equivalente para outro harness). O caso recursivo para o ecossistema em si é resolvido fazendo gitignore do estado de planos local ao harness em vez de migrá-lo fisicamente para o código-fonte.

Ferramentas. Para projetos já no layout legado — uma árvore irmã <project-root>/.plans/ mais armazenamentos <project-root>/.apothem/<harness>/{memory,contexts,learning} por harness — o comando apothem migrate-workspace colapsa ambos no diretório de trabalho compartilhado <project-root>/.apothem/{plans,memory,learning,contexts}. O comando é idempotente e não destrutivo: faz backup de cada fonte que consome, move .plans/ para .apothem/plans/, faz união-mesclagem dos armazenamentos de memória e contexto por harness, concatena-desduplica os sinais de aprendizado e nunca sobrescreve um registro conflitante. Execute apothem migrate-workspace --dry-run para pré-visualizar as movimentações primeiro.

A migração é idempotente e reversível até o momento da remoção do diretório de planos local ao harness (após o que um tarball de backup em ./.audit/plans-backup-<timestamp>.tar.gz fornece o artefato de reversão). Os exemplos abaixo usam ~/.claude/plans/; substitua pelo caminho equivalente para o harness ativo.

Etapa 1 — Inventário. Cada arquivo sob o diretório de planos local ao harness é enumerado e classificado como plan-artifact (quarantined).

Etapa 2 — Mapa de procedência. Um registro de procedência é construído para cada plano, com um projeto de destino inferido e uma pontuação de confiança derivada do campo project do frontmatter, sinais de varredura do corpo (URLs de repositórios, nomes de pacotes, caminhos absolutos) e pistas contextuais.

Etapa 3 — Confirmação de mapeamento. O mapa completo é apresentado ao operador como uma única consulta estruturada consolidada (ou uma sequência rigorosamente agrupada quando a contagem de arquivos excede um tamanho confortável para um único prompt). Para cada plano, o operador escolhe entre:

• Confirmar (Confirm) o projeto de destino inferido.
• Reatribuir (Reassign) a um projeto diferente (a opção apresenta a lista de projetos conhecidos do operador).
• Adiar (Defer) — mover para ~/.claude/.audit/orphan-plans/<original-name> para classificação posterior.
• Descartar (Discard) — apenas com uma consulta estruturada explícita e confirmada separadamente (isto é destrutivo).

Quando a confiança é high para muitos planos, o prompt oferece um recurso de confirmar-todos-os-de-alta-confiança para comprimir as idas e voltas, ainda expondo cada decisão individual no registro.

Etapa 4 — Preparação do projeto antes da movimentação. Para cada projeto de destino único:

1. Verifique que a raiz do projeto exista e seja legível.
2. Verifique que é um repositório git (para raízes não git, exponha pelo canal de consulta estruturada se prosseguir, inicializar ou pular).
3. Garanta que <project-root>/.apothem/plans/ exista; crie com mkdir -p se não.
4. Verifique que o .gitignore do projeto contenha o trecho canônico de §6; se ausente, anexe-o com um comentário de cabeçalho creditando esta migração.
5. Verifique que <project-root>/.apothem/plans/ ainda não esteja rastreado pelo git; se estiver (um erro de um colaborador anterior), exponha pelo canal de consulta estruturada com as opções parar-de-rastrear-e-manter, parar-de-rastrear-e-remover-do-histórico, abortar.

Etapa 5 — Movimentação. Para cada emparelhamento confirmado plano → destino:

1. Calcule o nome de arquivo de destino: se a fonte tiver frontmatter, normalize conforme §3; caso contrário, envolva o corpo com frontmatter (status draft, campo project definido, created a partir do mtime, tags [migrated]) e renomeie para YYYY-MM-DD--<slug>.md.
2. Se existir uma colisão de nomes no destino, anexe -imported-<unix-timestamp> e registre a renomeação.
3. Copie o arquivo (preservando mtime), verifique que o SHA-256 corresponda no destino, então desvincule a fonte.
4. Anexe uma entrada a <project-root>/.apothem/plans/_migration-manifest.md (também gitignored) registrando: o caminho original local ao harness, o caminho de destino, o SHA-256 original, o timestamp e a resposta de consulta estruturada que autorizou esta movimentação.

Etapa 6 — Verificação. Após todas as movimentações:

1. Confirme que o diretório de planos local ao harness esteja vazio (os planos órfãos, se houver, estão dentro do diretório de auditoria/quarentena daquele harness, fora do diretório que será excluído em breve).
2. Confirme que cada projeto de destino tenha um .apothem/plans/ populado e um manifesto.
3. Faça uma verificação por amostragem via SHA-256 de que o conteúdo migrado corresponde aos originais.

Etapa 7 — Tarball e remoção. Crie ./.audit/plans-backup-<ISO-timestamp>.tar.gz contendo toda a árvore de planos local ao harness anterior à movimentação (extraída de um snapshot temporário tirado na Etapa 1). Então, por meio de uma consulta estruturada final confirmando a prontidão, remova o diretório de planos local ao harness agora vazio.

Etapa 8 — Registro de auditoria. Emita ./.audit/plans-migration.md resumindo cada movimentação, cada arquivo adiado, cada descarte, cada renomeação por colisão e cada anexo ao gitignore.

6. Trecho de .gitignore posterior (canônico, copiar-colar)Copy Anchor Link

Todo projeto que adota este ecossistema DEVE adicionar o seguinte bloco ao seu .gitignore:

# Apothem working directory (project-local shared state: plans, memory,
# learning, contexts; gitignored — never committed). The sole canonical plans
# home is `.apothem/plans/`.
# See: <repo-url>/blob/main/site/content/docs/reference/plans-discipline.mdx
# Ignore the CONTENTS of this directory (not the directory) so the
# `.keep` negation below can take effect.
.apothem/*
!.apothem/.keep

A isenção opcional .keep preserva a existência do diretório em ferramentas que podam caminhos vazios, sem vazar conteúdo. Se incluir .keep é decidido por projeto pelo canal de consulta estruturada na primeira invocação de /plan. As linhas .apothem/* + !.apothem/.keep são o trecho canônico; um projeto que ainda carrega uma árvore legada <project-root>/.plans/ executa apothem migrate-workspace (§5) para atualizá-la para .apothem/plans/.

7. Mecanismos de autoaplicaçãoCopy Anchor Link

A disciplina deve sobreviver a cada sessão futura. As seguintes superfícies de aplicação são obrigatórias e estão codificadas no ecossistema publicado:

1. AGENTS.md e superfícies de instrução espelho — bloco de comportamento obrigatório de nível superior declarando: "Os artefatos de planejamento são escritos em <project-root>/.apothem/plans/ — o único lar canônico de planos (uma árvore legada <project-root>/.plans/ é atualizada via apothem migrate-workspace) — nunca em qualquer diretório de configuração do harness (por exemplo ~/.codex/ ou ~/.claude/) e nunca em uma localização global. Esta regra é inegociável; cite §3 da especificação do projeto em cada decisão relacionada." Este bloco é detectado pelo validador plans-discipline-language.
2. Arquivo de instruções no repositório por harness — espelha a mesma diretiva no enquadramento apropriado para a superfície de instrução daquele harness (§4 Disciplina de planos); detectado pelo mesmo validador em cada superfície de harness registrada.
3. Output-style padrão — quando uma resposta produziria conteúdo em forma de plano (estratégia de várias etapas, decomposição, percurso de projeto, diário de depuração), o estilo roteia o artefato para uma escrita em .apothem/plans/ local ao projeto em vez de imprimi-lo-e-descartá-lo inline. O estilo instrui explicitamente: "Se nenhuma raiz de projeto for descobrível, pare com uma consulta estruturada perguntando ao operador onde planejar."
4. Cada prompt de trabalhador delegado — carrega uma estrofe de Superfície de saída nomeando .apothem/plans/ como o destino de qualquer artefato de planejamento, e uma estrofe de Antipadrão nomeando os diretórios de planos locais ao harness como proibidos.
5. Um comando de barra /plan dedicado — aceita um slug + corpo, escreve em <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md com o frontmatter correto, garante que o .gitignore do destino esteja correto, recusa-se a escrever em caminhos de harness-config-root.
6. Um hook pre-tool-use — plan-write-guard — intercepta cada chamada de ferramenta de escrita de arquivo. Se o caminho de destino corresponde a uma localização de planos local ao harness (por exemplo ~/.claude/plans/... ou ~/.codex/.plans/...) ou qualquer outro caminho global do ecossistema que a heurística identifique como em forma de plano, o hook bloqueia a escrita e levanta uma consulta estruturada propondo o redirecionamento para o .apothem/plans/ do projeto atual.
7. Validadores de CI — no-global-plans faz a build falhar se a memória de trabalho de planos versionada reaparecer na árvore publicada; plans-discipline-language falha se a diretiva canônica desaparecer de qualquer arquivo de instruções de harness registrado ou do output-style padrão. As superfícies de destino canônicas do validador (preservadas como contratos do sistema de arquivos) estão listadas no bloco cercado abaixo.

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

8. Hooks de pre-commit — espelham o acima localmente para que a disciplina seja aplicada antes que qualquer commit aterrisse.

8. Antipadrões (categoricamente proibidos)Copy Anchor Link

• Escrever planos dentro de um diretório de configuração do harness (por exemplo ~/.claude/plans/ ou ~/.codex/.plans/) ou qualquer outra localização global.
• Versionar planos no histórico git de um projeto (hooks de tempo de commit deveriam rejeitar isto).
• Misturar planos com ADRs (ciclos de vida diferentes, localizações diferentes, status de versionamento diferente).
• Planos sem frontmatter, planos sem nomes de arquivo com prefixo de data, planos sem um campo project.
• Planos entre projetos (um plano, dois projetos). Divida-os — um plano por projeto.
• Compartilhar planos entre máquinas por meio de uma sincronização de configuração do harness (p. ex. ~/.claude para Claude Code) — um argumento estrutural para manter os planos locais ao projeto: o repositório do projeto é o mecanismo de sincronização, nas raras ocasiões em que os planos merecem ser compartilhados — e esse mérito é em si um sinal de que o conteúdo deveria ser promovido a um ADR.
• Conteúdo de plano embutido dentro de prompts de trabalhadores delegados, corpos de habilidades ou output-styles. Essas superfícies são configuração de comportamento duradoura; os planos são memória de trabalho transitória.
• Aplicar a linha SPDX do cabeçalho de autoria a um arquivo de plano (os planos são isentos por design — §2, site/content/docs/reference/authorship-header.mdx §Lista de exceções).

Veja tambémCopy Anchor Link

• ADR-0001 — justificativa arquitetural, alternativas consideradas, compensações aceitas.
• site/content/docs/reference/authorship-header.mdx — a disciplina da linha SPDX do cabeçalho de autoria (os planos são categoricamente isentos).
• A página de convenções do harness — convenções do harness multi-superfície (a Disciplina de planos aparece como uma afirmação compartilhada em cada arquivo de instruções de harness registrado e em cada superfície opcional aceita). Caminho:

site/content/docs/reference/ai-conventions.mdx

• Especificação do projeto §3 — o texto canônico completo espelhado aqui.