Lista de verificação de sincronização entre máquinas

Escopo. Esta lista de verificação verifica a camada de portabilidade de instalação / desinstalação do adaptador do Claude Code em um segundo host novo. Os demais harnesses têm suas próprias receitas de verificação por host, documentadas em site/content/docs/harnesses/<harness>.mdx.

Dois caminhos, dois papéis. Mantenha-os separados ao ler esta lista de verificação. $HOME/.apothem é o diretório do motor (engine home): é onde a árvore de código-fonte é clonada e de onde os instaladores leem, substituível com APOTHEM_HOME. ~/.claude/ é a raiz de configuração do Claude Code: a superfície de saída do adaptador, onde o settings.json materializado e a subárvore de suporte são gravados. O motor nunca é instalado em ~/.claude/; substitua pelo caminho de saída nativo do adaptador ao validar outro harness.

Verificação conduzida pelo operador da camada de portabilidade de instalação / desinstalação em um segundo host novo. O nível de publicação (vX.Y.Z) foi escrito em um único host Windows; a afirmação de portabilidade (CLAUDE.md portability: universal) precisa de um exercício de ponta a ponta em um segundo host antes que a invariante multi-host tenha peso. Esta lista de verificação é a receita canônica de verificação no segundo host (adaptador do Claude Code).

1. Pré-condições no segundo hostCopy Anchor Link

Execute no segundo host antes de iniciar a verificação:

2. Verificação de clonagem e instalaçãoCopy Anchor Link

Execute no segundo host:

# Clone the published repo to the engine home. This is NOT ~/.claude — that
# is the Claude Code configuration root the adapter writes into, and cloning
# a source tree on top of it would bury the harness's own config.
git clone https://github.com/ahmed-g-gad/apothem.git "$HOME/.apothem"
cd "$HOME/.apothem"

# (POSIX path) Run scripts/installer/install.sh dry-run first
bash scripts/installer/install.sh --dry-run                                    # exit 0; prints Dry-run complete — no changes were made.

# (POSIX path) Run scripts/installer/install.sh for real
bash scripts/installer/install.sh                                               # exit 0; idempotent

# (Windows path) PowerShell parallel
pwsh -File scripts/installer/install.ps1 -DryRun                                # exit 0; prints Dry-run complete - no changes were made.
pwsh -File scripts/installer/install.ps1                                        # exit 0

Registre o código de saída e o banner de stdout de cada comando. Grave em <second-host>/.audit/cross-machine-clone-install.md.

3. A disciplina dos quatro elementos (conforme src/apothem/rules/production-ready-prs.md)Copy Anchor Link

Verifique cada uma das quatro invariantes no segundo host:

3.1 Segurança do destino existenteCopy Anchor Link

# Re-run installer at the same destination.
bash scripts/installer/install.sh                                               # POSIX
pwsh -File scripts/installer/install.ps1                                        # Windows

Esperado: o instalador detecta o diretório do motor existente e faz checkout da tag de lançamento nele em vez de reinstalar ou duplicar; código de saída 0.

3.2 Verificação de pré-requisitosCopy Anchor Link

# Run from a copy outside any checkout, with git not on PATH.
d="$(mktemp -d)" && cp scripts/installer/install.sh "$d/" && PATH=<directory holding python3, click, rich and coreutils, but no git> /bin/sh "$d/install.sh"                            # POSIX (no git)

Esperado: o instalador se recusa a executar; emite um diagnóstico explícito "git not found"; código de saída diferente de zero.

3.3 Reexecução idempotenteCopy Anchor Link

# Run installer N times back-to-back.
for i in 1 2 3 4 5; do bash scripts/installer/install.sh; done                  # POSIX
1..5 | ForEach-Object { pwsh -File scripts/installer/install.ps1 }              # Windows

Esperado: cada invocação termina com código 0; nenhum efeito colateral após a primeira invocação; nenhum arquivo duplicado; nenhuma duplicação de RC do shell-profile.

3.4 Configurável por variáveis de ambienteCopy Anchor Link

# Install to a non-default engine home. APOTHEM_HOME is the destination
# override the installers actually read; see the installer-environment-variables
# reference for the full set.
APOTHEM_HOME=/tmp/alt-apothem bash scripts/installer/install.sh                 # POSIX
$env:APOTHEM_HOME='C:\tmp\alt-apothem'; pwsh -File scripts/installer/install.ps1   # Windows

Esperado: o instalador respeita a variável de ambiente; o padrão $HOME/.apothem NÃO é criado; o destino alternativo contém o layout esperado.

4. Verificação do conjunto de validadores (pós-instalação)Copy Anchor Link

cd "$HOME/.apothem"
make validate                                                 # conformity gate --all --strict; exit 0
make headers-doctor                                           # file-header-grep → passed:true
make ai-surfaces-doctor                                       # multi-surface-coherence → passed:true
make plans-doctor                                             # no-global-plans + plans-discipline-language
make lint                                                     # ruff check + ruff format --check + mypy
make test                                                     # exit 0, no failures

Esperado: todos os portões em verde. Registre os códigos de saída e as linhas de resumo.

5. Verificação da desinstalaçãoCopy Anchor Link

# POSIX path — interactive uninstall
bash scripts/installer/uninstall.sh                           # answers: "y" to confirm
PYTHONPATH="$HOME/.apothem/src/apothem/_vendor:$HOME/.apothem/src" python3 -m apothem verify --harness claude-code    # reports the harness as not installed

# Re-install from the kept checkout, then uninstall non-interactively
bash scripts/installer/install.sh
bash scripts/installer/uninstall.sh --yes
PYTHONPATH="$HOME/.apothem/src/apothem/_vendor:$HOME/.apothem/src" python3 -m apothem verify --harness claude-code    # reports the harness as not installed

Esperado: o fluxo interativo solicita confirmação; --yes dispensa a solicitação em execuções em lote; os dois fluxos deixam a raiz de configuração do Claude Code livre de arquivos materializados pelo Apothem; o shim apothem é removido (~/.local/bin/apothem; o shim apothem.cmd em %LOCALAPPDATA%\Microsoft\WindowsApps é removido somente por uninstall.ps1).

6. Verificação das salvaguardas de segurançaCopy Anchor Link

A salvaguarda do desinstalador é uma verificação de formato da árvore de código-fonte, não um arquivo sentinela: ela só prossegue quando o alvo contém src/apothem/ junto com pyproject.toml ou .claude-plugin/. Execute estas sondagens com APOTHEM_HOME, a variável que o script lê. Uma sondagem escrita contra uma variável ignorada pelo script não testa a salvaguarda: ela executa o desinstalador contra a sua instalação real.

# Run uninstall against a directory that is not an apothem source tree.
mkdir -p /tmp/not-an-apothem-install
APOTHEM_HOME=/tmp/not-an-apothem-install bash scripts/installer/uninstall.sh --yes

Esperado: o desinstalador se recusa e emite No apothem source found at /tmp/not-an-apothem-install — nothing to uninstall; código de saída diferente de zero. O caminho NÃO foi tocado.

# Run uninstall against $HOME and /.
APOTHEM_HOME=$HOME bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3
APOTHEM_HOME=/ bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3

Esperado: APOTHEM_HOME=$HOME e APOTHEM_HOME=/ recusam cada um com o diagnóstico No apothem source found at …, e nenhum dos dois toca o sistema de arquivos. Um APOTHEM_HOME vazio fica de fora de propósito: ele recai em ~/.apothem, onde pode haver uma instalação real.

# An explicit APOTHEM_SOURCE that is not a source tree is rejected separately.
APOTHEM_SOURCE=/tmp/not-an-apothem-install bash scripts/installer/uninstall.sh --yes

Esperado: recusa com APOTHEM_SOURCE is not an apothem source tree: /tmp/not-an-apothem-install; código de saída diferente de zero.

7. RelatórioCopy Anchor Link

Após a execução no segundo host, registre os resultados em:

• <second-host>/.audit/cross-machine-clone-install.md (resultados dos comandos de clonagem e de instalação)
• <second-host>/.audit/cross-machine-validators.md (resultados dos validadores da Seção 4)
• <second-host>/.audit/cross-machine-uninstall.md (resultados de desinstalação e de segurança das Seções 5–6)

Comunique os achados ao mantenedor:

• ✅ todas as invariantes da disciplina dos quatro elementos se sustentam, todos os portões de validadores estão em verde e todas as salvaguardas da desinstalação recusaram alvos inseguros → a afirmação portability: universal da publicação fica verificada de ponta a ponta
• ❌ qualquer falha → abra uma issue em https://github.com/ahmed-g-gad/apothem/issues/new com a seção que falhou e a saída capturada; o mantenedor faz a triagem

8. Critérios de aceitaçãoCopy Anchor Link

• §1 pré-condições atendidas
• §2 a clonagem e a instalação têm êxito tanto em shells POSIX quanto em shells Windows
• §3 a disciplina dos quatro elementos se sustenta (segurança do destino existente; pré-requisitos verificados; idempotente; configurável por variável de ambiente)
• §4 todos os portões de validadores em verde
• §5 a desinstalação interativa tem êxito; --yes tem êxito sem solicitação
• §6 cada recusa de salvaguarda é disparada
• §7 resultados registrados nos caminhos de auditoria documentados

Quando todas as caixas de seleção acima estiverem marcadas em um segundo host novo, a verificação de sincronização entre máquinas está concluída e a afirmação portability: universal fica verificada de ponta a ponta.