Guided setup planner: implementation contract deferred from ADR-0025 review #208

Summary

ADR-0025 (z-shell/.github#633, source issue z-shell/.github#632) decides that guided Zi setup ships first as a headless plan and apply pair in this repository. Its review surfaced implementation-contract questions that belong to the planner's design, not to the decision record. This issue owns them; the ADR stays at decision level.

Contract items from the ADR review

1. Startup block paths. Every source in the generated .zshrc block is prefixed with the resolved configuration-home variable (source "$ZI_LOADER_CONFIG_HOME/setup/pre.zsh" && source "$ZI_LOADER_CONFIG_HOME/init.zsh" && zzinit, then setup/shell.zsh the same way). Test startup from a working directory that is not the configuration home.
2. Legacy value extraction. Migrating ZI_HOME and ZI_BIN_DIR_NAME out of a legacy .zshrc block uses non-evaluating extraction and data-safe single-quoted Zsh serialization, like the -b ref; refuse migration when either value cannot be decoded unambiguously.
3. Checkout phase transaction. Record the expected checkout HEAD and ref in the plan, validate all checkout and file preconditions before any mutation, and lock both the configuration home and the checkout root; or make the checkout update a separately authorized phase with its own validation and lock.
4. Instruction routing. When the planner paths exist, add an implementation-facing route for them to .github/instruction-surfaces.json in z-shell/.github so implementation work receives ADR-0025 without broadening the ** decision route to all shell work. Part of the implementation pull request's impact review.
5. Symlinked .zshrc. A temp-file rename over a symlink replaces the link. Define handling explicitly: resolve and validate the link target through apply, or refuse and emit the patch without replacing the link.
6. Migration matrix. Cover every current installer profile: absorb the exact -a annex and -a zunit recipe blocks (the install.sh: the .zshrc probe matches comments, and the annex block is re-appended on every rerun #205 duplication case) into setup/shell.zsh; for the loader block, which does not encode ZI_HOME or ZI_BIN_DIR_NAME, discover the checkout path with conflict checks or refuse ambiguous installs with a supported remediation.

Related

• Defects this planner fixes on its path: install.sh: update path resets and cleans the zi checkout without confirmation, stricter than zi self-update #203, install.sh: annex profiles run an interactive zsh mid-install, executing the user's .zshenv and .zshrc #204, install.sh: the .zshrc probe matches comments, and the annex block is re-appended on every rerun #205
• Missing review skill on main: main has no code-review skill; the only copy is on the unmerged fix/codex-compatibility branch #207