Skip to content

Prevent Zsh special parameter name collisions in scoped guidance #546

Description

@ss-o

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

  1. Classification: scoped normative Zsh guidance plus its existing
    machine-readable enforcement metadata.
  2. 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.
  3. Canonical owner: .github/instructions/zsh-scripting.instructions.md
    remains the correct prose owner; lib/zsh-standard-policy.json remains the
    metadata owner.
  4. Duplication or contradiction: none found. Existing parameter rules cover
    explicit scope and dynamic scope, but not collisions with special parameter
    names.
  5. Manifest routing: no added, changed, or removed route is needed. The
    existing instruction-zsh-scripting surface already reaches the affected
    paths and consumers.
  6. Runtime delivery: yes. Every supported runtime receives the mandatory
    scoped instruction without relying on an optional hook or skill.
  7. 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

  • Canonical prose explains the status and path failure modes.
  • Policy metadata and exact validator inventories contain the new rule.
  • Startup-profile membership remains synchronized.
  • A focused test protects the failure-mode wording.
  • Public agent-policy and Zsh-policy tests and validators pass.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:metaOrganization-wide policy, templates, or meta-repo work.type:maintenanceNon-feature maintenance, cleanup, or org work.

    Type

    No type

    Projects

    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions