docs(branching): adopt trunk-on-main default

.github/instruction-surfaces.json

@@ -816,6 +816,23 @@
       "review_owner": "z-shell maintainers",
       "canonical_for": []
     },
+    {
+      "id": "decision-0019",
+      "path": "decisions/0019-trunk-on-main-default.md",
+      "kind": "decision",
+      "authority": "canonical-detail",
+      "consumers": ["codex", "claude-code", "copilot", "gemini-cli", "human"],
+      "tasks": [
+        "architecture-decision",
+        "branch-protection",
+        "repository-bootstrap",
+        "release"
+      ],
+      "file_patterns": ["**"],
+      "required": true,
+      "review_owner": "z-shell maintainers",
+      "canonical_for": ["branching-model"]
+    },
     {
       "id": "zsh-standard-policy",
       "path": "lib/zsh-standard-policy.json",

.github/instructions/github-actions-ci-cd-best-practices.instructions.md

@@ -21,7 +21,7 @@ Canonical guidelines for authoring, reviewing, and hardening GitHub Actions work
 name: CI
 on:
   push:
-    branches: [main, next]
+    branches: [main]
   pull_request:
 
 concurrency:

.github/instructions/testing.instructions.md

@@ -32,8 +32,9 @@ definitions come from `decisions/0007-release-publication-flow.md`.
 
 ## By class
 
-- **Class 1 — deployed:** the build must pass on the development branch before
-  deploy. Wiki: ESLint + Stylelint + production build. `zd`: Docker build matrix.
+- **Class 1, deployed:** the build must pass on pull requests into `main` and
+  on the merged `main` commit before deploy. Wiki: ESLint + Stylelint +
+  production build. `zd`: Docker build matrix.
   `src`: installer/loader validation. Add CodeQL where a supported language exists.
 - **Class 2, versioned tools:** a **full functional suite is required on the
   exact tag commit and gates release publication**. ZUnit for Zsh tools;
@@ -61,9 +62,13 @@ Do not add an org-wide coverage number.
 
 ## Required checks
 
-Mark the class-appropriate checks as required for merge to the publication branch
-(`main`, or `next`→`main` per ADR-0008). Class-3 repos require the baseline;
-class-2 repos additionally require the functional suite before a release tag.
+Mark the class-appropriate checks as required on the integration branch
+(`main`, or `zi`'s named `next` exception per ADR-0019). Class-3 repositories
+require the baseline; class-2 repositories additionally re-run the functional
+suite against the exact commit before a release tag is published.
+
+For `zi`, ordinary pull requests validate against `next`; the promotion pull
+request into `main` runs the full stable-branch check set on its exact head SHA.
 
 ## See also
 

.github/workflows/agent-instructions.yml

@@ -29,7 +29,6 @@ on:
   push:
     branches:
       - main
-      - next
     paths:
       - "AGENTS.md"
       - "PATTERNS.md"

.github/workflows/commit-lint.yml

@@ -6,8 +6,8 @@ name: Commit Lint
 # the AGENTS.md rules that were previously "author-enforced" only: the
 # disallowed bot/AI-agent Co-authored-by trailer -- a human co-author is
 # allowed, only a bot/agent identity is banned (AGENTS.md) -- Conventional
-# Commits (decisions/0003), and feature-<id>/bug-<id>/hotfix-<id> branch
-# naming (decisions/0008).
+# Commits (decisions/0003), and issue-linked topic-branch naming
+# (decisions/0019).
 
 on:
   workflow_call:
@@ -24,8 +24,8 @@ on:
         default: '^[[:space:]]*Co-authored-by:.*(\[bot\]|noreply@anthropic\.com|noreply@openai\.com|noreply@x\.ai|codex@openai\.com|copilot@github\.com|claude@anthropic\.com)'
       branch-pattern:
         description: >
-          grep -E pattern a PR head branch must match. dependabot/*,
-          renovate/*, and next are always allowed regardless of this pattern.
+          grep -E pattern a PR head branch must match. dependabot/* and
+          renovate/* are always allowed. next is allowed only for z-shell/zi.
         required: false
         type: string
         default: "^(feature|bug|hotfix)-[1-9][0-9]*$"
@@ -108,14 +108,15 @@ jobs:
         env:
           BRANCH: ${{ github.head_ref }}
           BRANCH_PATTERN: ${{ inputs.branch-pattern }}
+          REPOSITORY: ${{ github.repository }}
         run: |
           if echo "$BRANCH" | grep -qE '^(dependabot|renovate)/' || \
-             [ "$BRANCH" = "next" ]; then
+             { [ "$REPOSITORY" = "z-shell/zi" ] && [ "$BRANCH" = "next" ]; }; then
             echo "✅ OK"
             exit 0
           fi
           if ! echo "$BRANCH" | grep -qE "$BRANCH_PATTERN"; then
-            echo "::error::Branch name must match ${BRANCH_PATTERN} (see decisions/0008-branching-model.md)"
+            echo "::error::Branch name must match ${BRANCH_PATTERN} (see decisions/0019-trunk-on-main-default.md)"
             exit 1
           fi
           echo "✅ Branch name valid"

AGENTS.md

@@ -73,7 +73,7 @@ When working in z-shell repositories, optimize for:
 - **Canonical plugin manager:** `zi`. See `decisions/0002-zi-as-canonical-plugin-manager.md`.
 - **Commits and PR titles:** Conventional Commits. See `decisions/0003-conventional-commits.md`.
 - **Commit trailers:** `Co-authored-by` crediting a real human, including the PR author crediting themselves, is fine. Never credit a bot, AI agent, or automation as a co-author. `z-shell/.github` and `z-shell/zi` enforce this in CI. Other repositories remain author-enforced until their own verified caller is live; do not infer enforcement from organization policy alone.
-- **Branch selection:** Follow `decisions/0008-branching-model.md` and verify the live state of the owning repository; do not assume one universal default branch.
+- **Branch selection:** Follow `decisions/0019-trunk-on-main-default.md` and verify the live state of the owning repository; `zi` is the named persistent-integration exception.
 - **Worktrees:** Treat `git worktree list --porcelain` as the authoritative inventory. Use the owning repository's declared helper and stable worktree root; do not create worktrees in `/tmp` or another ad hoc location. Do not use a linked superproject checkout for work that needs initialized submodules. Follow `runbooks/worktrees.md`.
 - **Documentation placement:** keep long-form docs in the wiki when practical; keep repo-local docs focused on policy, workflow, and source-adjacent guidance.
 - **Workflow files:** follow the org workflow conventions and keep permissions explicit, actions pinned, and concurrency defined.
@@ -126,7 +126,9 @@ drafts only.
 
 ## PR conventions
 
-- Prefer squash merges unless a branch genuinely needs separate commits preserved.
+- Prefer squash merges unless a branch genuinely needs separate commits
+  preserved. `zi` promotion from persistent `next` to stable `main` is the
+  ancestry-preserving merge-commit exception defined by ADR-0019.
 - Link the related issue, PR, tracker item, or ADR.
 - When a PR makes or codifies a non-obvious decision, draft or update an ADR.
 - For unfinished work, include an `Agent handoff` section in the PR body or issue thread.

decisions/0007-release-publication-flow.md

@@ -25,8 +25,9 @@ formalizes.
 
 ### Repository classes and release policy
 
-1. **Continuously deployed artifacts** (`wiki`, `src`, `zd` images): validate on
-   the development branch; deploy via the repo's existing delivery model. No
+1. **Continuously deployed artifacts** (`wiki`, `src`, `zd` images): validate
+   pull requests into `main` and the merged `main` commit; deploy via the
+   repository's existing delivery controls. No
    tag-driven changelog/release automation unless a separate packaged artifact
    appears.
 2. **Versioned tools and packages** (`zunit`, `zsh-lint`, `zpmod`, packaged
@@ -70,8 +71,8 @@ Per-repo application:
   metadata) before wiring a release, since the artifact determines the steps.
   (`zsh#8`.)
 - **`zi`** — class 3, git-consumed; **no release automation added**. Its
-  `next → main → tag` boundary (`zi#346`) is governed by this policy but no
-  workflow or code change is made to `zi` under this ADR.
+  `next` to stable `main` promotion (`zi#346`) is governed by ADR-0019, while
+  this ADR adds no tag-driven release workflow to `zi`.
 
 ## Consequences
 

decisions/0008-branching-model.md

@@ -4,7 +4,7 @@
 - **Date:** 2026-07-25
 - **Deciders:** ss-o
 - **Supersedes:** None
-- **Superseded by:** None
+- **Superseded by:** `decisions/0019-trunk-on-main-default.md`
 
 ## Context
 

decisions/0009-testing-ci-strategy.md

@@ -16,8 +16,8 @@ statement of _what level of testing each repository class owes_, which makes it
 hard to know whether a repo is under- or over-tested, and what a reviewer should
 require before merge.
 
-ADR-0007 classified repositories by delivery model and ADR-0008 establishes a
-branch model informed by those classes. This ADR similarly establishes a
+ADR-0007 classified repositories by delivery model and ADR-0019 establishes a
+trunk-on-main branch model with one named integration exception. This ADR establishes a
 target CI scope by class, accepted with owned rollout gaps: it does not claim
 that every listed control is already live or configured as a required check.
 
@@ -53,7 +53,8 @@ rollout status per repository is tracked in issue #454, not restated here.
 ### By class
 
 1. **Continuously deployed artifacts** (`wiki`, `src`, `zd`) — the build succeeds
-   on the development branch before deploy. The target checks cover the wiki's
+   on pull requests into `main` and on the merged `main` commit before deploy.
+   The target checks cover the wiki's
    lint and production build, `zd`'s Docker build matrix, and `src`'s
    installer/loader validation, plus CodeQL where a supported language is
    present.
@@ -85,10 +86,11 @@ ratcheting is a per-repo maintainer decision.
 ### Required checks
 
 Under the target policy, each repository marks its class-appropriate checks as
-required for merge to its publication branch (`main`, or `next` → `main` per
-ADR-0008). Validation-only repositories require the baseline; class-2
-repositories additionally require the functional suite. Required checks,
-development-branch validation, SAST coverage, and the release-suite gate are
+required for merge to its integration branch (`main`, or `zi`'s named `next`
+exception per ADR-0019). Validation-only repositories require the baseline;
+class-2 repositories additionally require the functional suite on the exact
+commit before publishing a tag. Required checks,
+integration-branch validation, SAST coverage, and the release-suite gate are
 each verified repository by repository through owning issues; the presence of
 a workflow file is not by itself treated as proof that a check is required or
 that a ruleset enforces it.
@@ -119,7 +121,7 @@ that a ruleset enforces it.
 ## References
 
 - `decisions/0007-release-publication-flow.md` — repository classes.
-- `decisions/0008-branching-model.md` — branch model per class.
+- `decisions/0019-trunk-on-main-default.md` - branch model and named exception.
 - `decisions/0005-workflow-naming-conventions.md` — workflow naming baseline.
 - `decisions/0012-hybrid-dependency-management.md` — dependency-update and
   vulnerability-remediation ownership.