Skip to content

chore(branching): adopt trunk-on-main default and retain zi integration #550

Description

@ss-o

Objective

Implement the 2026-08-28 maintainer decision to make protected trunk-on-main
the organization default and retain next -> main only for z-shell/zi.

Decision

Accepted by maintainer ss-o on 2026-08-28:

  • src, wiki, zsh-lint, and zsh-eza migrate to trunk-on-main.
  • zi retains next as its integration branch because main is a directly
    consumed stable ref and the repository has a distinct promotion qualification
    suite.
  • Persistent next -> main promotion uses a merge commit. The destination
    branch does not require linear history, and routine squash reconciliation is
    retired.
  • Deployment and publication controls remain separate from code integration:
    class 1 uses reviewed main plus deployment controls; class 2 publishes from
    annotated tags; class 3 uses reviewed refs according to its assigned model.

Required deliverables

  • Supersede ADRs 0008 and 0016 with an accepted replacement decision.
  • Reconcile branch protection, release, dependency, onboarding, and new-repo
    runbooks plus routed instructions and validators.
  • Promote all outstanding wiki and zsh-lint integration work before
    retiring their persistent branches.
  • Migrate src, wiki, zsh-lint, and zsh-eza workflows, dependency
    targets, documentation, rulesets, and repository settings to main.
  • Correct zi promotion mechanics and rulesets while retaining next.
  • Update the private workspace catalog and regenerate its instruction
    composite.
  • Prove every retired next branch is represented in main, has no open
    dependent pull requests, then remove its ruleset and branch.
  • Run repository-specific checks and a final live settings audit.

Instruction impact review

  1. Classification: shared branching policy, scoped operational guidance, and
    repository enforcement.
  2. Consumers: maintainers and all supported agent runtimes across the public
    organization policy, affected repositories, and private control workspace.
  3. Canonical owner: a new ADR in z-shell/.github, with operational detail in
    the existing branch, release, dependency, onboarding, and bootstrap runbooks.
  4. Duplicate or contradictory surfaces: ADRs 0008 and 0016, ADR 0013 rationale,
    branch-protection and release reconciliation procedures, child AGENTS.md,
    workflow contracts, dependency targets, and the wiki contributor guide.
  5. Manifest routing: no new route is expected; existing branch-protection,
    workflow, documentation, and instruction-change routes remain the owners.
  6. Runtime delivery: the public AGENTS.md reference and private generated
    composite will be updated and validated without relying on optional hooks.
  7. Validation: public policy validators, private generation checks,
    repository-specific tests, workflow parsing/actionlint, and live ruleset and
    branch audits.

Triage

  • Item type: Chore
  • Impact: High
  • Effort: XL
  • Priority: P1
  • Workstream: Administrative

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:ciContinuous integration or GitHub Actions work.area:metaOrganization-wide policy, templates, or meta-repo work.priority:highNeeds prompt attention.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