Lista de verificación de sincronización entre máquinas

Alcance. Esta lista de verificación comprueba la capa de portabilidad de instalación y desinstalación del adaptador de Claude Code en un segundo host nuevo. Otros entornos tienen sus propias recetas de verificación por host documentadas en site/content/docs/harnesses/<harness>.mdx.

Dos rutas, dos funciones. Mantenlas separadas mientras lees esta lista. $HOME/.apothem es el directorio base del motor: donde se clona el árbol de código fuente y desde donde leen los instaladores, sustituible con APOTHEM_HOME. ~/.claude/ es la raíz de configuración de Claude Code: la superficie de salida del adaptador, donde aterrizan el settings.json materializado y el subárbol de soporte. El motor nunca se instala en ~/.claude/; sustituye la ruta de salida nativa del adaptador al validar otro entorno.

Verificación dirigida por el operador de la capa de portabilidad de instalación / desinstalación en un segundo host nuevo. El nivel de publicación (vX.Y.Z) se redactó en un único host Windows; la afirmación de portabilidad (CLAUDE.md portability: universal) necesita una ejecución de extremo a extremo en un segundo host antes de que la invariante multi-host tenga peso. Esta lista de verificación es la receta canónica de verificación en un segundo host (adaptador de Claude Code).

1. Condiciones previas en el segundo hostCopy Anchor Link

Ejecuta en el segundo host antes de iniciar la verificación:

2. Verificación de clonado e instalaciónCopy Anchor Link

Ejecuta en el 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

Captura el código de salida y el banner de stdout de cada comando. Regístralo en <second-host>/.audit/cross-machine-clone-install.md.

3. La disciplina de los cuatro elementos (según src/apothem/rules/production-ready-prs.md)Copy Anchor Link

Verifica cada una de las cuatro invariantes en el segundo host:

3.1 Seguridad del 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: El instalador detecta el directorio base del motor existente y hace checkout de la etiqueta de lanzamiento en él en lugar de reinstalar o duplicar; código de salida 0.

3.2 Prerrequisitos comprobadosCopy 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: El instalador se niega a ejecutarse; emite un diagnóstico explícito "git not found"; código de salida distinto de cero.

3.3 Reejecución 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 invocación termina con código 0; sin efectos secundarios tras la primera invocación; sin archivos duplicados; sin duplicación de RC en el perfil del shell.

3.4 Configurable mediante variables de entornoCopy 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: El instalador respeta la variable de entorno; el valor predeterminado $HOME/.apothem NO se crea; el destino alternativo contiene la estructura esperada.

4. Verificación del conjunto de validadores (posterior a la instalación)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: Todas las puertas en verde. Captura los códigos de salida y las líneas de resumen.

5. Verificación de la desinstalaciónCopy 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: El flujo interactivo solicita confirmación; --yes omite la solicitud en ejecuciones por lotes; ambos flujos dejan la raíz de configuración de Claude Code libre de archivos materializados por Apothem; se elimina el shim apothem (~/.local/bin/apothem; el shim apothem.cmd en %LOCALAPPDATA%\Microsoft\WindowsApps solo lo elimina uninstall.ps1).

6. Verificación de las salvaguardas de seguridadCopy Anchor Link

La salvaguarda del desinstalador es una comprobación de la forma del árbol de código fuente, no un archivo centinela: solo procede cuando el destino contiene src/apothem/ junto con pyproject.toml o .claude-plugin/. Ejecuta estas sondas con APOTHEM_HOME, la variable que lee el script; una sonda escrita contra una variable que el script ignora no prueba la salvaguarda, sino que ejecuta el desinstalador contra tu instalación 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: El desinstalador se niega; emite No apothem source found at /tmp/not-an-apothem-install — nothing to uninstall; código de salida distinto de cero. La ruta NO fue tocada.

# 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 y APOTHEM_HOME=/ se niegan cada uno con el diagnóstico No apothem source found at …, y ninguno toca el sistema de archivos. Un APOTHEM_HOME vacío se deja fuera a propósito: recurre a ~/.apothem, donde puede estar una instalación 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: Se niega con APOTHEM_SOURCE is not an apothem source tree: /tmp/not-an-apothem-install; código de salida distinto de cero.

7. InformesCopy Anchor Link

Tras la ejecución en el segundo host, captura los resultados en:

• <second-host>/.audit/cross-machine-clone-install.md (resultados de los comandos de clonado e instalación)
• <second-host>/.audit/cross-machine-validators.md (resultados de los validadores de la sección 4)
• <second-host>/.audit/cross-machine-uninstall.md (resultados de desinstalación y seguridad de las secciones 5–6)

Comunica los hallazgos al mantenedor:

• ✅ se cumplen todas las invariantes de la disciplina de los cuatro elementos, todas las puertas de validadores están en verde y todas las salvaguardas de desinstalación rechazaron los destinos inseguros → la afirmación portability: universal de la publicación queda verificada de extremo a extremo
• ❌ cualquier fallo → abre una incidencia en https://github.com/ahmed-g-gad/apothem/issues/new con la sección que falló y la salida capturada; el mantenedor la clasifica

8. Criterios de aceptaciónCopy Anchor Link

• §1 condiciones previas cumplidas
• §2 el clonado e instalación tienen éxito tanto en shells POSIX como en Windows
• §3 se cumple la disciplina de los cuatro elementos (seguridad del destino existente; prerrequisitos comprobados; idempotencia; configurable mediante variables de entorno)
• §4 todas las puertas de validadores en verde
• §5 la desinstalación interactiva tiene éxito; --yes tiene éxito sin solicitud
• §6 se dispara cada rechazo de las salvaguardas de seguridad
• §7 resultados capturados en las rutas de auditoría documentadas

Cuando todas las casillas anteriores estén marcadas en un segundo host nuevo, la verificación de sincronización entre máquinas estará completa y la afirmación portability: universal quedará verificada de extremo a extremo.