Skip to content

[initiative]: Deliver clean portable Zsh plugin architecture #556

Open
9 of 10 issues completed
Open
[initiative]: Deliver clean portable Zsh plugin architecture#556
9 of 10 issues completed
Assignees
ss-o
Labels
area:metaOrganization-wide policy, templates, or meta-repo work.meta:initiativeMarks a parent issue coordinating two or more independently deliverable sub-issues.meta:org-trackedIndicates this issue has cross-repository tracking implications (synced to Linear).type:maintenanceNon-feature maintenance, cleanup, or org work.

Description

@ss-o
ss-o
opened on Aug 28, 2026

Outcome

Publish and enforce a clean, portable Zsh Plugin Standard that gives plugin
authors one maintainable set of rules for repository layout, configuration,
namespaces, public shell surface, loading, and exact lifecycle ownership.

When complete, maintained z-shell plugins use the same portable contract. The
contract contains no legacy compatibility mode for shared Plugins state,
scattered public configuration parameters, generic persistent functions, or
unowned load-time effects.

Context

The current public standard is strong on plugin-manager interoperability and
Zsh semantics, but it does not completely define the architectural decisions
that make a multi-plugin ecosystem predictable to users and contributors.
Current organization templates, static analysis, runtime tests, and active
plugin implementations therefore permit different configuration and state
shapes despite sharing a namespace rule.

This initiative coordinates the public standard, static and runtime
enforcement, organization scaffolding, and the first conforming plugin
implementation without creating a private z-shell-only technical standard.

Expected deliverables

  • z-shell/wiki: publish the revised portable standard through the active H2
    review issue.
  • z-shell/zsh-lint: enforce high-confidence static project-contract rules.
  • z-shell/zunit: provide reusable runtime lifecycle assertions.
  • z-shell/.github: adopt the contract in policy, templates, review guidance,
    routing, and CI requirements.
  • z-shell/zsh-fancy-completions: make PR build(deps): bump github/codeql-action from 2.1.32 to 2.1.33 #62 the clean-break pilot with
    namespaced zstyle configuration and exact ownership restoration.
  • Maintained plugin repositories: migrate through separately owned issues and
    pull requests after the pilot proves the contract.

Dependencies and risks

The public standard decision blocks enforcement design. Released static and
runtime tooling blocks organization-required pins and the pilot migration.
Organization adoption blocks the wider repository rollout.

Risks include false-positive static rules, lifecycle observers that mutate the
shell while taking snapshots, and over-standardizing implementation details
that do not affect interoperability. Each rule therefore needs official Zsh
evidence, deterministic fixtures, and an explicit portable rationale.

Completion criteria

  • The canonical public standard defines the complete portable contract.
  • Static and runtime enforcement are released and immutably pinned.
  • Organization templates produce a conforming plugin without cleanup.
  • PR build(deps): bump github/codeql-action from 2.1.32 to 2.1.33 #62 passes the new contract with no legacy compatibility surface.
  • Every maintained plugin has migrated or has an explicit tracked blocker.
  • Required deliverables are complete or explicitly descoped.

Activity

  1. ss-o
    added
    type:maintenanceNon-feature maintenance, cleanup, or org work.
    area:metaOrganization-wide policy, templates, or meta-repo work.
    status:triageAwaiting initial review or classification.
    meta:org-trackedIndicates this issue has cross-repository tracking implications (synced to Linear).
    meta:initiativeMarks a parent issue coordinating two or more independently deliverable sub-issues.
    on Aug 28, 2026
  2. github-project-automation
    added this to Z-shell Deliveryon Aug 28, 2026
  3. github-project-automation
    moved this to Triage in Z-shell Deliveryon Aug 28, 2026
  4. ss-o
    added sub-issues on Aug 28, 2026
  5. ss-o
    moved this from Triage to In Progress in Z-shell Deliveryon Aug 28, 2026
  6. ss-o
    added sub-issues on Aug 28, 2026

  7. ss-o commented on Aug 28, 2026

    @ss-o
    ss-o
    on Aug 28, 2026
    MemberAuthor

    Implementation checkpoint

    Status: Implementation published; release and adoption sequence remains blocked.

    Deliverable Pull request Current state
    Portable Standard 2 z-shell/wiki#893 Open, checks passing
    Static project-contract enforcement z-shell/zsh-lint#188 Open, checks passing
    Runtime lifecycle assertions z-shell/zunit#19 Open, checks passing
    Organization policy, template, ADR, and routing #558 Draft, checks passing, blocked on the standard and released tool pins
    Clean-break pilot z-shell/zsh-fancy-completions#62 Draft, locally verified, hosted tool checks intentionally blocked on pre-v2 pins

    The standard now separates manager-independent portable rules from optional loader interfaces. Its portable-core validator rejects PMSPEC, ZPFX, zsh_loaded_plugins, and @zsh-plugin-* dependencies inside the core contract.

    The pilot removes shared Plugins state, public ZFC_* configuration parameters, legacy feature mapping, and alternate public namespaces. It configures through :zfc:config, uses the zfc identifier, and proves the exact load and ownership-aware unload surface with the new ZUnit assertions.

    No tool release, merge, organization-policy acceptance, or pilot pin update has been performed. The required order remains:

    1. Review and merge the public standard.
    2. Review, merge, and release zsh-lint and ZUnit.
    3. Replace policy and pilot workflow references with commits from those releases.
    4. Rerun required checks, review the proposed ADR, and only then advance the blocked draft PRs.

    Zi automatic unload currently derives the callback name from the repository basename, which does not match a shorter portable identifier such as zfc. The pilot does not add a second compatibility namespace. A Zi manager-profile improvement is a separate scope decision.

  8. ss-o
    added a sub-issue on Aug 28, 2026

  9. ss-o commented on Aug 29, 2026

    @ss-o
    ss-o
    on Aug 29, 2026
    MemberAuthor

    Delivery update

    The organization adoption PR #558 can now replace any prerelease tool pins with
    these released commit SHAs. The plugin PR remains a separate maintainer review
    and merge action.

  10. ss-o
    self-assigned this
    on Aug 31, 2026
  11. ss-o
    removed
    status:triageAwaiting initial review or classification.
    on Aug 31, 2026
  12. ss-o
    added a sub-issue on Sep 2, 2026
  13. ss-o
    added a sub-issue on Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:metaOrganization-wide policy, templates, or meta-repo work.meta:initiativeMarks a parent issue coordinating two or more independently deliverable sub-issues.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

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions