Summary

Formalises the release-cut branch model (sometimes called gitflow-lite) that the framework repo has been operating under informally since the start of this hooks-wave. dev is daily-work; main only receives release PRs from dev; each release-PR merge tags a semver. Adopters' /update skill pulls upstream/main, which is now strictly release-only — no more WIP commits leaking to forks.

Framework-only. This pattern is for me2resh/apexyard itself. Managed projects under apexyard governance (entries in apexyard.projects.yaml) stay trunk-based — they have no downstream consumers and don't need the ceremony. Both CLAUDE.md and docs/multi-project.md call this out explicitly so the pattern doesn't cargo-cult into project templates.

Added:

• AgDR-0007 — decision record with the options table (full git flow vs trunk-only vs gitflow-lite — chose gitflow-lite)
• /release skill at .claude/skills/release/SKILL.md — diffs dev against main, proposes a semver bump from conventional-commit types, generates a CHANGELOG draft, opens the release PR, tags + pushes after merge
• docs/release-process.md — prose runbook (the skill is the automation; the doc is the manual fallback + conceptual reference)
• .git.protected_branches in project-config.defaults.json (default [main, master, dev, develop])

Modified:

• block-main-push.sh — extended to block direct pushes/commits to ALL protected branches, not just main/master. Reads the list from project config via the shared reader ([Chore] Make ticket-prefix whitelist + schema project-configurable (not hardcoded) #109). Forks that legitimately use dev as a working trunk under their own convention can override.
• CLAUDE.md — new "Branch model — framework only" subsection under Git Conventions. /release added to the skills table.
• docs/multi-project.md — note in the "Upgrades" section that upstream/main is release-only as of v1.2.0 + reminder that the split applies to apexyard itself, not to managed projects.

Testing

No automated tests (the /release skill is a markdown spec; block-main-push.sh extension is verified by tracing the regex against the protected list).

Manual smoke:

# Hook respects the new protected list
echo '{"tool_input":{"command":"git push origin dev"}}' | bash .claude/hooks/block-main-push.sh
# → exit 2, "Cannot push directly to a protected branch"

# Hook still blocks main
echo '{"tool_input":{"command":"git push origin main"}}' | bash .claude/hooks/block-main-push.sh
# → exit 2

# Feature-branch push still allowed
echo '{"tool_input":{"command":"git push origin chore/GH-116-foo"}}' | bash .claude/hooks/block-main-push.sh
# → exit 0

The first real /release invocation will be the v1.2.0 cut — at that point we'll dogfood the skill end-to-end and any rough edges show up there.

Scope — what this does NOT do

• No automatic on-merge issue close for dev-targeting PRs. GitHub auto-close only fires on default-branch merges. The release PR's body aggregates all Closes #N for the batch and triggers auto-close en masse when it merges to main. Manual close-with-merge-trace in the meantime (see closing pattern on [Chore] Make ticket-prefix whitelist + schema project-configurable (not hardcoded) #109/[Chore] block-private-refs-in-public-repos.sh — hook to scrub registry names from upstream tickets #110/[Chore] warn-stale-review-markers.sh — surface invalidated reviews at push-time, not merge-time #115/[Chore] pre-push-gate.sh — upgrade from advisory reminder to blocking check-runner #111/[Chore] validate-issue-structure.sh — config-driven PreToolUse hook for gh issue create #107/[Chore] require-agdr-for-arch-pr.sh — block gh pr create when diff touches architecture without AgDR link #112/[Chore] Require Testing section in PR body (extend validate-pr-create.sh) #113/[Chore] Enforce single Closes-keyword per PR body (one ticket per PR) #114). A small post-merge automation could be a follow-up.
• No release/* or hotfix/* branches. Hotfixes are just patches cut quickly. If multi-version maintenance becomes a real need, revisit AgDR-0007.
• No CI workflow edits — pull_request triggers fire regardless of base branch, so dev-targeting PRs already get the full check matrix.

Branch protection (manual GitHub setting)

For maintainers of me2resh/apexyard, configure GitHub branch protection on main per docs/release-process.md § Branch protection:

• Require pull request before merging
• Require approvals: 1
• Require all status checks to pass
• (Optional) Restrict who can push (admins only, for the rare manual tag-fix case)

This is documentation-only here — the actual GitHub setting is a one-time admin action.

Glossary

Closes #116