ci: switch branching to main+release, drop dev branch

- CI now runs on push to main (was dev)
- Release workflow triggers on push to release (was main)
- Changelog archives to main with release fast-forward
- Updated all docs to reflect new branch pattern

Author: atomantic

.changelog/README.md

@@ -79,22 +79,31 @@ Update `.changelog/v0.2.x.md` **every time** you add features and fixes:
 - Keep the version in the file as `v0.2.x` (literal x)
 - Don't worry about the final patch number - it will be substituted automatically
 
-### Before Merging to Main
+### Before Releasing
 
-Final review before release:
+Final review before pushing to `release`:
 - Ensure all changes are documented
 - Add release date (update "YYYY-MM-DD" to actual date)
 - Review and polish the content
 - Commit the changelog file
+- Bump version in `package.json`
+
+### Triggering a Release
+
+Push main to the release branch:
+
+```bash
+git push origin main:release
+```
 
 ### On Release
 
 The GitHub Actions workflow automatically:
 1. Reads `.changelog/v0.2.x.md`
 2. Replaces all instances of `0.2.x` with the actual version (e.g., `0.2.5`)
 3. Creates the GitHub release with the substituted changelog
-4. Renames `v0.2.x.md` → `v0.2.5.md` (preserves git history)
-5. Bumps dev to next minor version
+4. Renames `v0.2.x.md` → `v0.2.5.md` on `main` (preserves git history)
+5. Fast-forwards `release` to match `main`
 
 ### After Release
 

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [dev]
-  pull_request:
     branches: [main]
+  pull_request:
+    branches: [main, release]
 
 # Cancel duplicate runs for the same branch/PR
 concurrency:

.github/workflows/release.yml

@@ -2,7 +2,7 @@ name: Release
 
 on:
   push:
-    branches: [main]
+    branches: [release]
 
 permissions:
   contents: write
@@ -100,41 +100,30 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Archive changelog on dev branch
+      - name: Archive changelog on main
         if: steps.tag-check.outputs.exists == 'false'
         run: |
           CURRENT_VERSION=${{ steps.package-version.outputs.version }}
           MAJOR=$(echo $CURRENT_VERSION | cut -d. -f1)
           MINOR=$(echo $CURRENT_VERSION | cut -d. -f2)
           MAJOR_MINOR="$MAJOR.$MINOR"
 
-          # Checkout dev branch
-          git fetch origin dev
-          git checkout dev
-
-          # Rename and version the changelog file
           PATTERN_FILE=".changelog/v${MAJOR_MINOR}.x.md"
           VERSIONED_FILE=".changelog/v${CURRENT_VERSION}.md"
 
           if [ -f "$PATTERN_FILE" ]; then
-            # Rename the file (preserves git history)
-            git mv "$PATTERN_FILE" "$VERSIONED_FILE"
+            # Archive directly on main so release never diverges
+            git fetch origin main
+            git checkout main
 
-            # Replace version placeholders in the renamed file
-            sed -i.bak "s/v${MAJOR_MINOR}\.x/v${CURRENT_VERSION}/g; s/${MAJOR_MINOR}\.x/${CURRENT_VERSION}/g" "$VERSIONED_FILE"
+            git mv "$PATTERN_FILE" "$VERSIONED_FILE"
+            sed -i.bak "s/v${MAJOR_MINOR}\.x/v${CURRENT_VERSION}/g; s/${MAJOR_MINOR}\.x/${CURRENT_VERSION}/g; s/YYYY-MM-DD/$(date +%Y-%m-%d)/g" "$VERSIONED_FILE"
             rm "${VERSIONED_FILE}.bak"
 
-            # Commit the renamed and updated changelog
             git add "$VERSIONED_FILE"
             git commit -m "docs: archive changelog for v${CURRENT_VERSION} [skip ci]"
-            git push origin dev
-
-            # Store the changelog commit SHA before switching branches
-            CHANGELOG_COMMIT=$(git rev-parse HEAD)
-
-            # Merge changelog back to main (without triggering CI)
-            git checkout main
-            git cherry-pick "$CHANGELOG_COMMIT"
             git push origin main
-            git checkout dev
+
+            # Fast-forward release to match main
+            git push origin main:release
           fi

CLAUDE.md

@@ -75,9 +75,10 @@ Layer 1: Raw Provider Cache → JSON files (data/person/*.json)
 
 ## Git Workflow
 
-- **dev**: Active development (auto-bumps patch on CI)
-- **main**: Production releases only
+- **main**: Active development
+- **release**: Push `main` to `release` to trigger GitHub Release workflow
 - **Push pattern**: `git pull --rebase --autostash && git push`
+- **Release**: `git push origin main:release`
 - **Changelog**: Update `.changelog/v{major}.{minor}.x.md` with changes
 - **Commit often**: After each feature or bug fix
 

docs/development.md

@@ -103,17 +103,28 @@ The browser profile is stored in `.browser/data/` to persist logins.
 
 ### Branches
 
-- **dev**: Active development (auto-bumps patch on CI pass)
-- **main**: Production releases only
+- **main**: Active development
+- **release**: Push `main` to `release` to trigger the GitHub Release workflow
 
 ### Pushing Changes
 
-The dev branch receives auto version bump commits from CI. Always use rebase:
+Always use rebase:
 
 ```bash
 git pull --rebase --autostash && git push
 ```
 
+### Releasing
+
+```bash
+# 1. Bump version in package.json
+# 2. Ensure .changelog/v{major}.{minor}.x.md is up to date
+# 3. Push to main, then trigger release:
+git push origin main:release
+```
+
+The release workflow will create a GitHub Release, archive the changelog on `main`, and fast-forward the `release` branch to match.
+
 ### Commit Guidelines
 
 - Create commits after each feature or bug fix
@@ -126,7 +137,7 @@ All release notes are maintained in `.changelog/v{major}.{minor}.x.md` files:
 
 1. Add entries under appropriate emoji sections during development
 2. Keep version as `0.3.x` (CI replaces with actual version on release)
-3. Final review before merging `dev → main`
+3. Final review before pushing to `release`
 
 See `.changelog/README.md` for detailed format.