Prüfliste zur maschinenübergreifenden Synchronisation

Geltungsbereich. Diese Prüfliste verifiziert die Install- / Uninstall-Portabilitätsschicht des Adapters für Claude Code auf einem frischen zweiten Host. Andere Harnesses haben eigene Verifizierungsrezepte pro Host, dokumentiert unter site/content/docs/harnesses/<harness>.mdx.

Zwei Pfade, zwei Rollen. Halte sie beim Lesen dieser Prüfliste auseinander. $HOME/.apothem ist das Engine-Home — der Ort, an dem der Quellbaum geklont wird und von dem die Installer lesen; überschreibbar mit APOTHEM_HOME. ~/.claude/ ist die Konfigurationswurzel von Claude Code — die Ausgabeoberfläche des Adapters, in der die materialisierte settings.json und der Unterstützungs-Teilbaum landen. Die Engine wird niemals in ~/.claude/ installiert; verwende beim Validieren eines anderen Harness stattdessen den adapter-nativen Ausgabepfad.

Vom Operator getriebene Verifizierung der Install- / Uninstall-Portabilitätsschicht auf einem frischen zweiten Host. Die Veröffentlichungsstufe (vX.Y.Z) wurde auf einem einzelnen Windows-Host verfasst; die Portabilitätsaussage (CLAUDE.md portability: universal) braucht eine durchgängige Erprobung auf einem zweiten Host, bevor die Multi-Host-Invariante Gewicht trägt. Diese Prüfliste ist das kanonische Verifizierungsrezept für den zweiten Host (Adapter für Claude Code).

1. Vorbedingungen auf dem zweiten HostCopy Anchor Link

Auf dem zweiten Host vor Beginn der Verifizierung ausführen:

2. Verifizierung von Klonen und InstallationCopy Anchor Link

Auf dem zweiten Host ausführen:

# 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

Exit-Code und stdout-Banner jedes Befehls erfassen. Aufzeichnen unter <second-host>/.audit/cross-machine-clone-install.md.

3. Die Vier-Elemente-Disziplin (gemäß src/apothem/rules/production-ready-prs.md)Copy Anchor Link

Jede der vier Invarianten auf dem zweiten Host verifizieren:

3.1 Sicherheit des bestehenden ZielsCopy Anchor Link

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

Erwartet: Der Installer erkennt das bestehende Engine-Home und checkt darin das Release-Tag aus, statt neu zu installieren oder zu duplizieren; Exit-Code 0.

3.2 Voraussetzungen geprüftCopy 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)

Erwartet: Der Installer verweigert die Ausführung; gibt eine explizite "git not found"-Diagnose aus; Exit-Code ungleich null.

3.3 Idempotenter erneuter LaufCopy 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

Erwartet: Jeder Aufruf endet mit 0; keine Nebenwirkungen nach dem ersten Aufruf; keine doppelten Dateien; keine Duplizierung im Shell-Profil-RC.

3.4 Konfigurierbar über UmgebungsvariablenCopy 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

Erwartet: Der Installer berücksichtigt die Umgebungsvariable; das Standardverzeichnis $HOME/.apothem wird NICHT angelegt; das alternative Ziel enthält das erwartete Layout.

4. Verifizierung der Validator-Suite (nach der Installation)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

Erwartet: Jedes Gate grün. Exit-Codes und Zusammenfassungszeilen erfassen.

5. Verifizierung der DeinstallationCopy 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

Erwartet: Der interaktive Ablauf fragt nach; --yes überspringt die Abfrage bei Batch-Läufen; beide Abläufe lassen die Konfigurationswurzel von Claude Code frei von durch Apothem materialisierten Dateien; der apothem-Shim wird entfernt (~/.local/bin/apothem; der Shim apothem.cmd in %LOCALAPPDATA%\Microsoft\WindowsApps wird nur von uninstall.ps1 entfernt).

6. Verifizierung der SicherheitsschutzvorrichtungenCopy Anchor Link

Die Schutzvorrichtung des Deinstallers ist eine Prüfung der Quellbaum-Struktur und keine Sentinel-Datei: Sie läuft nur weiter, wenn das Ziel src/apothem/ zusammen mit entweder pyproject.toml oder .claude-plugin/ enthält. Steuere diese Probes mit APOTHEM_HOME, der Variable, die das Skript liest. Eine Probe, die gegen eine Variable geschrieben ist, die das Skript ignoriert, prüft die Schutzvorrichtung nicht; sie führt den Deinstaller gegen deine echte Installation aus.

# 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

Erwartet: Der Deinstaller verweigert; gibt No apothem source found at /tmp/not-an-apothem-install — nothing to uninstall aus; Exit-Code ungleich null. Der Pfad wurde NICHT berührt.

# 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

Erwartet: APOTHEM_HOME=$HOME und APOTHEM_HOME=/ verweigern jeweils mit der Diagnose No apothem source found at …, und keiner von beiden berührt das Dateisystem. Ein leeres APOTHEM_HOME ist absichtlich ausgelassen: Es fällt auf ~/.apothem zurück, wo eine echte Installation liegen kann.

# 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

Erwartet: Verweigert mit APOTHEM_SOURCE is not an apothem source tree: /tmp/not-an-apothem-install; Exit-Code ungleich null.

7. BerichterstattungCopy Anchor Link

Nach dem Lauf auf dem zweiten Host die Ergebnisse erfassen unter:

• <second-host>/.audit/cross-machine-clone-install.md (Ergebnisse der Klon- und Installationsbefehle)
• <second-host>/.audit/cross-machine-validators.md (Validator-Ergebnisse aus Abschnitt 4)
• <second-host>/.audit/cross-machine-uninstall.md (Deinstallations- und Sicherheitsergebnisse aus Abschnitt 5–6)

Befunde dem Maintainer melden:

• ✅ alle Invarianten der Vier-Elemente-Disziplin halten + alle Validator-Gates grün + alle Sicherheitsschutzvorrichtungen der Deinstallation haben unsichere Ziele verweigert → die Aussage portability: universal der Veröffentlichung ist durchgängig verifiziert
• ❌ jeder Fehler → ein Issue unter https://github.com/ahmed-g-gad/apothem/issues/new mit dem fehlgeschlagenen Abschnitt und der erfassten Ausgabe anlegen; der Maintainer triagiert

8. AkzeptanzkriterienCopy Anchor Link

• §1 Vorbedingungen erfüllt
• §2 Klonen und Installation gelingen in POSIX- und Windows-Shells
• §3 die Vier-Elemente-Disziplin hält (Sicherheit des bestehenden Ziels; Voraussetzungen geprüft; idempotent; über Umgebungsvariable konfigurierbar)
• §4 jedes Validator-Gate grün
• §5 die interaktive Deinstallation gelingt; --yes gelingt ohne Abfrage
• §6 jede Verweigerung durch eine Sicherheitsschutzvorrichtung greift
• §7 Ergebnisse unter den dokumentierten Audit-Pfaden erfasst

Wenn jedes Kästchen oben auf einem frischen zweiten Host abgehakt ist, ist die Synchronisationsverifizierung über Maschinen hinweg abgeschlossen und die Aussage portability: universal ist durchgängig verifiziert.