ci: enforce branch model, conventional commits, and no-AI-files policy

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,43 +1,47 @@
-<!--- Provide a general summary of your changes in the Title above -->
+<!--
+  Thanks for contributing to zi! Please read the checklist below.
 
-## Description
-
-<!--- Describe your changes in detail -->
+  Branch model:
+    • Create your branch FROM next:  git checkout -b fix/my-fix next
+    • Open this PR TARGETING next — never target main directly
+    • main is only updated from next via a release PR
 
-## Motivation and Context
+  Commit messages must follow Conventional Commits:
+    type(scope): short description   (≤72 chars, imperative mood)
+    Types: feat  fix  perf  refactor  docs  test  ci  chore  revert
+    Example: fix(self-update): correctly propagate exit code on failure
 
-<!--- Why is this change required? What problem does it solve? -->
-<!--- If it fixes an open issue, please link to the issue here. -->
+  See .github/copilot-instructions.md for full guidelines.
+-->
 
-## How Has This Been Tested?
-
-<!--- Please describe in detail how you tested your changes. -->
-<!--- Include details of your testing environment, and the tests you ran to -->
-<!--- see how your change affects other areas of the code, etc. -->
+## Description
 
-## Screenshots (if appropriate):
+<!-- Describe your changes clearly. What problem does this solve? -->
 
-## Types of changes
+## Related issues
 
-<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+<!-- Closes #NNN  /  Part of #NNN  /  N/A -->
 
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to change)
-- [ ] Documentation update (if none of the other choices apply)
-- [ ] Chore (general maintenance, refactoring, or code style update)
+## Type of change
 
-## Checklist:
+<!-- Put an `x` in all boxes that apply -->
 
-<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
-<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+- [ ] `fix` — bug fix (non-breaking)
+- [ ] `feat` — new feature (non-breaking)
+- [ ] `feat!` / `fix!` — breaking change
+- [ ] `perf` — performance improvement
+- [ ] `refactor` — code change with no functional impact
+- [ ] `docs` — documentation only
+- [ ] `ci` — CI/workflow change
+- [ ] `chore` — maintenance / dependency bump
 
-- [ ] My code follows the code style of this project.
-- [ ] I have read the **CONTRIBUTING** document.
-- [ ] I have added tests to cover my changes.
-- [ ] All new and existing tests passed.
-- [ ] I have updated the documentation accordingly.
+## Checklist
 
-## Other information (if applicable)
+- [ ] My branch was created from `next` (not `main`)
+- [ ] This PR targets the `next` branch
+- [ ] Commit messages follow Conventional Commits format
+- [ ] No AI co-author trailers in commit messages
+- [ ] I have read [CONTRIBUTING.md](docs/CONTRIBUTING.md)
+- [ ] Existing tests pass (`zsh -n zi.zsh` / Trunk checks)
+- [ ] Documentation updated if needed
 
-<!--- Any other information that is important to this PR such as environment variables, special considerations, etc. -->

.github/copilot-instructions.md

@@ -0,0 +1,52 @@
+# GitHub Copilot Instructions for zi
+
+## Commit messages
+
+- Use **Conventional Commits** format: `type(scope): short description`
+- Allowed types: `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `ci`, `chore`, `revert`
+- Subject line: imperative mood, ≤72 characters, no trailing period
+- Body: wrap at 72 characters, explain *what* and *why* (not *how*)
+- **Never add AI co-author trailers** — do not append `Co-authored-by: Copilot`, `Co-authored-by: Claude`, `Co-authored-by: GitHub Copilot`, or any AI-generated attribution to commit messages
+- Breaking changes: add `!` after the type (`feat!:`) and include `BREAKING CHANGE:` in the footer
+
+Examples:
+```
+feat(loader): add lazy-loading for completions
+
+Defer completion setup until first TAB press to cut startup time
+for users with large fpath trees.
+
+BREAKING CHANGE: ZI_COMPLETION_LAZY must be set before zi is sourced.
+```
+
+```
+fix(self-update): correctly set exit code on network failure
+```
+
+## Branch model
+
+```
+main  ← production releases (tags only, squash-merged from next)
+next  ← integration branch (PR target for all work)
+  └─ feat/<name>    feature branches
+  └─ fix/<name>     bug-fix branches
+  └─ perf/<name>    performance improvements
+  └─ docs/<name>    documentation updates
+  └─ ci/<name>      CI/workflow changes
+  └─ chore/<name>   maintenance, refactors
+```
+
+- **All branches must be created from `next`**, not `main`
+- Open PRs **targeting `next`**, never `main` directly
+- `next` → `main` is the only path to production; it requires all CI checks to pass
+
+## AI-generated files
+
+- Do **not** suggest adding `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.aider*`, or similar AI-specific config files to this repository
+- Copilot configuration lives **only** in `.github/copilot-instructions.md`
+
+## Code style
+
+- Zsh files: 2-space indent, `# vim: ft=zsh sw=2 ts=2 et` modeline, LF endings
+- Every plugin entry file must resolve `$0` via the ZERO pattern
+- Follow the [Z-Shell Plugin Standard](https://wiki.zshell.dev/community/zsh_plugin_standard)

.github/workflows/commit-lint.yml

@@ -0,0 +1,116 @@
+---
+name: "📝 Commit Lint"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+    branches:
+      - main
+      - next
+
+permissions:
+  pull-requests: read
+  contents: read
+
+jobs:
+  commit-lint:
+    name: "📝 Validate Commits"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "⤵️ Check out code from GitHub"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: "📝 Lint commit messages"
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+
+          CONVENTIONAL_PATTERN='^(feat|fix|perf|refactor|docs|test|ci|chore|revert)(\([^)]+\))?!?: .{1,72}$'
+          AI_COAUTHOR_PATTERN='Co-authored-by:.*[Cc]opilot|Co-authored-by:.*[Cc]laude|Co-authored-by:.*[Gg][Pp][Tt]|Co-authored-by:.*[Oo]pen[Aa][Ii]|Co-authored-by:.*[Gg]emini|Co-authored-by:.*[Cc]ursor'
+
+          errors=0
+
+          while IFS= read -r sha; do
+            subject=$(git show -s --format='%s' "$sha")
+            body=$(git show -s --format='%b' "$sha")
+
+            # Skip merge commits
+            parent_count=$(git cat-file -p "$sha" | grep -c '^parent' || true)
+            if [ "$parent_count" -gt 1 ]; then
+              echo "⏭  Skip merge commit: $sha"
+              continue
+            fi
+
+            # Validate conventional commit subject
+            if ! echo "$subject" | grep -qE "$CONVENTIONAL_PATTERN"; then
+              echo "❌ $sha — subject does not follow Conventional Commits:"
+              echo "   Got:      $subject"
+              echo "   Expected: type(scope): description  (≤72 chars)"
+              errors=$((errors + 1))
+            else
+              echo "✅ $sha — $subject"
+            fi
+
+            # Block AI co-author trailers
+            full_message=$(git show -s --format='%B' "$sha")
+            if echo "$full_message" | grep -qE "$AI_COAUTHOR_PATTERN"; then
+              echo "❌ $sha — AI co-author trailer detected:"
+              echo "$full_message" | grep -E "$AI_COAUTHOR_PATTERN" | sed 's/^/   /'
+              errors=$((errors + 1))
+            fi
+          done < <(git log --format='%H' "${BASE_SHA}..${HEAD_SHA}")
+
+          if [ "$errors" -gt 0 ]; then
+            echo ""
+            echo "💡 Fix commits with: git rebase -i ${BASE_SHA}"
+            echo "   See .github/copilot-instructions.md for commit guidelines."
+            exit 1
+          fi
+
+          echo ""
+          echo "✅ All commit messages are valid."
+
+  pr-title:
+    name: "📋 Validate PR Title"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📋 Check PR title follows Conventional Commits"
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          PATTERN='^(feat|fix|perf|refactor|docs|test|ci|chore|revert)(\([^)]+\))?!?: .{1,72}$'
+          if ! echo "$PR_TITLE" | grep -qE "$PATTERN"; then
+            echo "❌ PR title does not follow Conventional Commits format."
+            echo "   Got:      $PR_TITLE"
+            echo "   Expected: type(scope): short description"
+            echo "   Types:    feat, fix, perf, refactor, docs, test, ci, chore, revert"
+            exit 1
+          fi
+          echo "✅ PR title: $PR_TITLE"
+
+  branch-naming:
+    name: "🌿 Validate Branch Name"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "🌿 Check branch naming convention"
+        env:
+          BRANCH: ${{ github.head_ref }}
+        run: |
+          PATTERN='^(feat|fix|perf|refactor|docs|test|ci|chore|revert)/[a-z0-9][a-z0-9-]*[a-z0-9]$'
+          # Allow dependabot branches
+          if echo "$BRANCH" | grep -q '^dependabot/'; then
+            echo "✅ Dependabot branch: $BRANCH"
+            exit 0
+          fi
+          if ! echo "$BRANCH" | grep -qE "$PATTERN"; then
+            echo "❌ Branch name does not follow naming convention."
+            echo "   Got:      $BRANCH"
+            echo "   Expected: type/short-description"
+            echo "   Example:  feat/lazy-completions  fix/self-update-exit-code"
+            exit 1
+          fi
+          echo "✅ Branch name: $BRANCH"

.github/workflows/trunk-check.yml

@@ -2,7 +2,7 @@
 name: Trunk Code Quality
 on:
   push:
-    branches: [main]
+    branches: [main, next]
     tags: ["v*.*.*"]
   pull_request:
     types: [opened, synchronize]

.gitignore

@@ -127,4 +127,15 @@ TAGS
 CVS
 .#*
 
-.trunk/out*
+.trunk/out*
+# AI assistant config files — not part of this project
+# (Copilot config belongs in .github/copilot-instructions.md only)
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.cursorrules
+.cursorignore
+.aider*
+.continue/
+.codeium/
+.tabnine*

docs/CONTRIBUTING.md

@@ -1,7 +1,58 @@
-# Contributing Guidelines
+# Contributing to zi
 
-When contributing, please first [discuss](https://github.com/z-shell/zi/issues/new/choose) the change you wish. The
-[contributing guidelines](https://github.com/z-shell/community/blob/main/docs/CONTRIBUTING_GUIDELINES.md) and other relevant documents can be found in the
-[community](https://github.com/z-shell/community) repository.
+Thank you for contributing! Please follow the guidelines below to keep the project history clean and easy to navigate.
+
+## Branch model
+
+```
+main  ←─── production (tagged releases only)
+  ↑
+next  ←─── integration branch  ← open all PRs here
+  ↑
+  ├── feat/<name>      new features
+  ├── fix/<name>       bug fixes
+  ├── perf/<name>      performance improvements
+  ├── refactor/<name>  code refactors
+  ├── docs/<name>      documentation updates
+  └── ci/<name>        CI / workflow changes
+```
+
+1. **Always branch from `next`**: `git checkout -b fix/my-issue next`
+2. **Open PRs targeting `next`** — never target `main` directly
+3. `next` → `main` happens via a release PR once `next` is stable
+
+## Commit message format
+
+All commits must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): short description
+
+Optional body — explain what and why, not how.
+Wrap at 72 characters.
+
+Optional footer(s):
+Fixes #123
+BREAKING CHANGE: description of what breaks
+```
+
+**Allowed types:** `feat` `fix` `perf` `refactor` `docs` `test` `ci` `chore` `revert`
+
+**Rules:**
+- Subject line: imperative mood, ≤72 characters, no trailing period
+- Breaking changes: use `!` suffix (`feat!:`) and add `BREAKING CHANGE:` footer
+- **No AI co-author trailers** — do not add `Co-authored-by: Copilot` or similar
+
+To clean up commits before opening a PR: `git rebase -i $(git merge-base HEAD next)`
+
+## What not to add
+
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, or any AI-specific config files
+- Secrets, credentials, or tokens of any kind
+
+## Discussion and issues
+
+Before starting significant work, [open an issue](https://github.com/z-shell/zi/issues/new/choose) to discuss the change.
+
+See also the [community contributing guidelines](https://github.com/z-shell/community/blob/main/docs/CONTRIBUTING_GUIDELINES.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.