Summary
The canonical Zsh scripting guidance does not explicitly prevent unrelated
scratch variables from reusing shell-owned special parameter names. That can
turn an ordinary local declaration into a runtime failure or a change to shell
state.
The released Zsh manual identifies status as the exit-status parameter and
path as the array tied to PATH. A clean-shell probe confirms that assigning
to a local status fails because it is read-only, while localizing path
changes command lookup through PATH.
Proposed change
- Add one required scoped rule covering all five execution profiles.
- Require purpose-specific names instead of repurposing Zsh special parameters
for unrelated local or scratch data.
- Keep the machine-readable rule catalog, validator inventories, startup
membership, and deterministic tests synchronized.
- Preserve the existing instruction route and canonical owner.
Instruction impact review
- Classification: scoped normative Zsh guidance plus its existing
machine-readable enforcement metadata.
- Consumers and contexts: Codex, Claude Code, Copilot, Gemini CLI, and
human contributors working with enrolled Zsh source in standalone,
startup-file, sourced-library, autoload-function, and test-fixture profiles.
- Canonical owner:
.github/instructions/zsh-scripting.instructions.md
remains the correct prose owner; lib/zsh-standard-policy.json remains the
metadata owner.
- Duplication or contradiction: none found. Existing parameter rules cover
explicit scope and dynamic scope, but not collisions with special parameter
names.
- Manifest routing: no added, changed, or removed route is needed. The
existing instruction-zsh-scripting surface already reaches the affected
paths and consumers.
- Runtime delivery: yes. Every supported runtime receives the mandatory
scoped instruction without relying on an optional hook or skill.
- Generated output and limits: the public agent-policy and Zsh-policy
validators pass. The private generated root composite is unaffected because
this does not change the imported public baseline or private overlay.
Acceptance criteria
References
Summary
The canonical Zsh scripting guidance does not explicitly prevent unrelated
scratch variables from reusing shell-owned special parameter names. That can
turn an ordinary local declaration into a runtime failure or a change to shell
state.
The released Zsh manual identifies
statusas the exit-status parameter andpathas the array tied toPATH. A clean-shell probe confirms that assigningto a local
statusfails because it is read-only, while localizingpathchanges command lookup through
PATH.Proposed change
for unrelated local or scratch data.
membership, and deterministic tests synchronized.
Instruction impact review
machine-readable enforcement metadata.
human contributors working with enrolled Zsh source in standalone,
startup-file, sourced-library, autoload-function, and test-fixture profiles.
.github/instructions/zsh-scripting.instructions.mdremains the correct prose owner;
lib/zsh-standard-policy.jsonremains themetadata owner.
explicit scope and dynamic scope, but not collisions with special parameter
names.
existing
instruction-zsh-scriptingsurface already reaches the affectedpaths and consumers.
scoped instruction without relying on an optional hook or skill.
validators pass. The private generated root composite is unaffected because
this does not change the imported public baseline or private overlay.
Acceptance criteria
statusandpathfailure modes.References
runbooks/instruction-update.mddecisions/0015-zsh-scripting-standard.md