Cross-Machine Sync Verification Checklist

Scope. This checklist verifies the Claude Code adapter install / uninstall portability layer on a fresh second host. Other harnesses have their own per-host verification recipes documented under site/content/docs/harnesses/<harness>.mdx.

Two paths, two roles. Keep them apart while reading this checklist. $HOME/.apothem is the engine home — where the source tree is cloned and where the installers read from, overridable with APOTHEM_HOME. ~/.claude/ is the Claude Code configuration root — the adapter's output surface, where materialized settings.json and the support subtree land. The engine is never installed into ~/.claude/; substitute the adapter-native output path when validating a different harness.

Operator-driven verification of the install / uninstall portability layer on a fresh second host. The publication tier (vX.Y.Z) was authored on a single Windows host; the portability claim (CLAUDE.md portability: universal) needs end-to-end exercise on a second host before the multi-host invariant carries weight. This checklist is the canonical second-host verification recipe (Claude Code adapter).

1. Pre-Conditions on the Second Host

Run on the second host before starting the verification:

2. Clone-and-Install Verification

Execute on the second 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; Quick Start banner

# (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; Quick Start banner
pwsh -File scripts/installer/install.ps1                                        # exit 0

Capture each command's exit code and stdout banner. Record at <second-host>/.audit/cross-machine-clone-install.md.

3. The Four-Element Discipline (per src/apothem/rules/production-ready-prs.md)

Verify each of the four invariants on the second host:

3.1 Existing-Destination Safety

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

Expected: Installer detects the existing engine home, fast-forwards rather than re-installing or duplicating; exit 0.

3.2 Prerequisite-Checked

# Temporarily move git out of PATH.
PATH=/usr/bin:/bin bash scripts/installer/install.sh                            # POSIX (no git)

Expected: Installer refuses to run; emits explicit "git not found" diagnostic; exit non-zero.

3.3 Idempotent Re-Run

# 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

Expected: Every invocation exits 0; no side effects after the first invocation; no duplicate files; no shell-profile RC duplication.

3.4 Configurable via Environment Variables

# 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

Expected: Installer honors the env-var; the default $HOME/.apothem is NOT created; the alt destination contains the expected layout.

4. Validator-Suite Verification (Post-Install)

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 + mypy
make test                                                     # exit 0, no failures

Expected: Every gate green. Capture exit codes + summary lines.

5. Uninstall Verification

# POSIX path — interactive uninstall
bash scripts/installer/uninstall.sh                           # answers: "y" to confirm
apothem verify --harness claude-code                          # reports the harness as not installed

# Re-install from clone, then uninstall non-interactively
git clone https://github.com/ahmed-g-gad/apothem.git "$HOME/.apothem"
bash scripts/installer/uninstall.sh --yes
apothem verify --harness claude-code                          # reports the harness as not installed

Expected: Interactive flow prompts; --yes skips the prompt for batch runs; both flows leave the Claude Code configuration root free of Apothem-materialized files; companion shell-profile env-var references are cleaned up.

6. Safety-Guard Verification

The uninstaller's guard is a source-tree shape check, not a sentinel file: it proceeds only when the target holds src/apothem/ alongside either pyproject.toml or .claude-plugin/. Drive these probes with APOTHEM_HOME, the variable the script reads — a probe written against a variable the script ignores does not test the guard, it runs the uninstaller against your real install.

# 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

Expected: Uninstaller refuses; emits No apothem source found at /tmp/not-an-apothem-install — nothing to uninstall; exit non-zero. The path was NOT touched.

# Run uninstall against $HOME, /, and an empty path.
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
APOTHEM_HOME='' bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3

Expected: Each refuses with the same No apothem source found at … diagnostic, because none of the three holds the source-tree shape; none touch the filesystem.

# 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

Expected: Refuses with APOTHEM_SOURCE is not an apothem source tree: /tmp/not-an-apothem-install; exit non-zero.

7. Reporting

After the second-host run, capture results at:

• <second-host>/.audit/cross-machine-clone-install.md (clone + install command outcomes)
• <second-host>/.audit/cross-machine-validators.md (Section 4 validator outcomes)
• <second-host>/.audit/cross-machine-uninstall.md (Section 5–6 uninstall + safety outcomes)

Surface findings to the maintainer:

• ✅ all four-element discipline invariants hold + all validator gates green + all uninstall safety guards refused unsafe targets → publication's portability: universal claim is verified end-to-end
• ❌ any failure → file an issue at https://github.com/ahmed-g-gad/apothem/issues/new with the failing section + captured output; the maintainer triages

8. Acceptance Criteria

• §1 pre-conditions met
• §2 clone-and-install succeeds on both POSIX and Windows shells
• §3 four-element discipline holds (existing-destination safety; prerequisite-checked; idempotent; env-var configurable)
• §4 every validator gate green
• §5 interactive uninstall succeeds; --yes succeeds without prompt
• §6 every safety-guard refusal fires
• §7 results captured at the documented audit paths

When every checkbox above is ticked on a fresh second host, the cross-machine sync verification is complete and the portability: universal claim is verified end-to-end.