You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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.
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.
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.
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.
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.
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.
Summary
ADR-0025 (z-shell/.github#633, source issue z-shell/.github#632) decides that guided Zi setup ships first as a headless
planandapplypair 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
sourcein the generated.zshrcblock is prefixed with the resolved configuration-home variable (source "$ZI_LOADER_CONFIG_HOME/setup/pre.zsh" && source "$ZI_LOADER_CONFIG_HOME/init.zsh" && zzinit, thensetup/shell.zshthe same way). Test startup from a working directory that is not the configuration home.ZI_HOMEandZI_BIN_DIR_NAMEout of a legacy.zshrcblock uses non-evaluating extraction and data-safe single-quoted Zsh serialization, like the-bref; refuse migration when either value cannot be decoded unambiguously.HEADand 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..github/instruction-surfaces.jsonin 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..zshrc. A temp-file rename over a symlink replaces the link. Define handling explicitly: resolve and validate the link target throughapply, or refuse and emit the patch without replacing the link.-a annexand-a zunitrecipe blocks (the install.sh: the .zshrc probe matches comments, and the annex block is re-appended on every rerun #205 duplication case) intosetup/shell.zsh; for the loader block, which does not encodeZI_HOMEorZI_BIN_DIR_NAME, discover the checkout path with conflict checks or refuse ambiguous installs with a supported remediation.Related
main: main has no code-review skill; the only copy is on the unmerged fix/codex-compatibility branch #207