Skip to content

feat(zsh): establish organization scripting standard #493

Description

@ss-o

Problem

Z-Shell has Zsh-first conventions, plugin examples, reviewer prompts, and CI
helpers, but no single organization standard that applies whenever Zsh source
is read, reviewed, diagnosed, created, or changed. The generic shell
instruction currently mixes Bash defaults into Zsh, and optional tools can be
mistaken for language authority.

Proposed outcome

  • make the current released official Zsh manual the semantic authority
  • add one canonical path-scoped Zsh instruction with stable rule IDs
  • record stable-release, execution-profile, and source-class metadata in one
    validated JSON policy
  • classify standalone, sourced, autoload, and test execution profiles
  • retain a repository-owned minimum Zsh version plus a current-stable CI model
  • rewrite generic shell guidance as a dialect dispatcher
  • deliver concise mandatory behavior through AGENTS.md
  • route the public standard through validated generated-composite delivery
  • keep native Zsh validation authoritative over supplemental parsers, linters,
    and formatters

First bounded increment

This issue's first implementation covers the proposed ADR, canonical standard,
machine policy, public validation and routing, reconciled optional consumers,
and generated-composite routing. It does not enroll another repository.

Deferred increments

  • tracked-source classifier and exact-version CI
  • repository enrollment and generated child delivery
  • zsh-lint and formatter ratchets
  • organization rollout and stable-release maintenance

Instruction impact review

  1. This is shared policy, scoped guidance, and enforcement.
  2. Codex, Claude Code, Copilot, humans, public standalone clones, and validated
    generated composites must receive the applicable rule. Gemini CLI is
    deprecated and is not a verification target.
  3. Public AGENTS.md owns the concise mandate,
    .github/instructions/zsh-scripting.instructions.md owns normative prose,
    and lib/zsh-standard-policy.json owns machine-readable release and
    classification data.
  4. The generic shell instruction, Zsh reviewer, plugin skill and template,
    ZUnit skill, and PATTERNS.md must defer to those owners.
  5. The public manifest needs new Zsh instruction, policy, validator, and ADR
    entries. Generated-composite consumers need separate task-only and path-only
    Zsh routes.
  6. Every supported runtime receives mandatory behavior through public
    AGENTS.md or the generated private composite. No optional hook, skill, or
    agent is required.
  7. Public validators, applicable generator checks, route tests,
    generated-output checks, and the 32,768-byte limit must pass.

Acceptance criteria

  • official Zsh 5.9.2 metadata and documentation URLs are recorded and validated
  • every normative rule has a stable ID and validated metadata
  • recognized Zsh paths receive the canonical instruction for every task
  • Zsh-in-.sh is handled by dialect classification, not suffix assumptions
  • ShellCheck is never prescribed for Zsh
  • optional consumers link to canonical rule IDs without redefining policy
  • public and applicable generated-delivery validation pass
  • the ADR remains PROPOSED
  • no child repository is enrolled

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:metaOrganization-wide policy, templates, or meta-repo work.meta:org-trackedIndicates this issue has cross-repository tracking implications (synced to Linear).type:maintenanceNon-feature maintenance, cleanup, or org work.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions