From 97a3ea1c7ba0f5d8c913fa726ceb70bd15847838 Mon Sep 17 00:00:00 2001
From: metaversedance <mattikaikah@gmail.com>
Date: Wed, 11 Feb 2026 12:15:30 -1000
Subject: [PATCH] Add develop branch CI gates and branching workflow docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enable CI validation for PRs targeting the develop branch by adding
it to pull_request triggers in ci.yml and pr-check.yml. Document the
feature/* → develop → master branching strategy and branch protection
rules.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
---
 .github/workflows/ci.yml       |   2 +-
 .github/workflows/pr-check.yml |   2 +-
 docs/BRANCHING.md              | 124 +++++++++++++++++++++++++++++++++
 3 files changed, 126 insertions(+), 2 deletions(-)
 create mode 100644 docs/BRANCHING.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 787661ad..49a925ae 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,7 +4,7 @@ on:
   push:
     branches: [master, main, develop]
   pull_request:
-    branches: [master, main]
+    branches: [master, main, develop]
   workflow_dispatch:
 
 # SECURITY: Restrict default permissions (principle of least privilege)
diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
index 9d252cff..42f92d71 100644
--- a/.github/workflows/pr-check.yml
+++ b/.github/workflows/pr-check.yml
@@ -2,7 +2,7 @@ name: PR Check
 
 on:
   pull_request:
-    branches: [master, main]
+    branches: [master, main, develop]
 
 jobs:
   # ===========================================================================
diff --git a/docs/BRANCHING.md b/docs/BRANCHING.md
new file mode 100644
index 00000000..303ea46e
--- /dev/null
+++ b/docs/BRANCHING.md
@@ -0,0 +1,124 @@
+# ForgeV3 Branching Strategy
+
+## Branch Model
+
+```
+feature/*  ──PR──>  develop  ──PR──>  master  ──auto-deploy──>  production
+hotfix/*   ──PR──>  master   (emergency only, cherry-pick back to develop)
+```
+
+## Branches
+
+| Branch | Purpose | Auto-deploys? | Protected? |
+|--------|---------|---------------|------------|
+| `master` | Production-ready code. Always deployable. | Yes — pushes trigger deploy to production | Yes |
+| `develop` | Integration branch. Collects feature work. | No | Yes |
+| `feature/*` | Individual features, fixes, improvements | No | No |
+| `hotfix/*` | Emergency production fixes | No (merged to master, which deploys) | No |
+
+## Workflow
+
+### Feature Development
+
+1. Create a feature branch from `develop`:
+   ```bash
+   git checkout develop && git pull
+   git checkout -b feature/my-feature
+   ```
+
+2. Work on your feature, commit, push:
+   ```bash
+   git push -u origin feature/my-feature
+   ```
+
+3. Open a PR targeting `develop`. CI runs automatically (lint, tests, security, Docker build check).
+
+4. After review and CI passes, merge into `develop`.
+
+### Promoting to Production
+
+1. Open a PR from `develop` into `master`.
+2. Full CI pipeline runs again (lint, all tests, security).
+3. After review and CI passes, merge into `master`.
+4. CI automatically builds Docker images, deploys to production, and runs DAST + performance tests.
+
+### Hotfixes
+
+For emergency production fixes that can't wait for the normal flow:
+
+1. Branch from `master`:
+   ```bash
+   git checkout master && git pull
+   git checkout -b hotfix/critical-fix
+   ```
+
+2. Fix, push, PR into `master`.
+3. After merge and deploy, cherry-pick the fix back to `develop`:
+   ```bash
+   git checkout develop && git pull
+   git cherry-pick <commit-hash>
+   git push
+   ```
+
+## CI Check Matrix
+
+| Event | `pr-check.yml` | `ci.yml` (full pipeline) | Docker push | Deploy | DAST + Perf |
+|-------|----------------|--------------------------|-------------|--------|-------------|
+| PR → `develop` | Yes | Yes | No | No | No |
+| PR → `master` | Yes | Yes | No | No | No |
+| Push to `develop` | — | Yes | Yes (tagged `develop`) | No | No |
+| Push to `master` | — | Yes | Yes (tagged `latest`) | Yes | Yes |
+| Tag `v*` | — | — | Yes (tagged with version) | — | — |
+
+## Branch Protection Rules
+
+Configure these in GitHub repo settings (Settings > Branches > Branch protection rules).
+
+### Protect `master`
+
+```bash
+gh api repos/SunFlash12/ForgeV3/branches/master/protection --method PUT --input - <<'EOF'
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [
+      "Lint & Type Check",
+      "Backend Tests",
+      "Frontend Build",
+      "Security Analysis",
+      "Validate PR",
+      "Docker Build Check"
+    ]
+  },
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true
+  },
+  "enforce_admins": true,
+  "restrictions": null
+}
+EOF
+```
+
+### Protect `develop`
+
+```bash
+gh api repos/SunFlash12/ForgeV3/branches/develop/protection --method PUT --input - <<'EOF'
+{
+  "required_status_checks": {
+    "strict": false,
+    "contexts": [
+      "Validate PR",
+      "Docker Build Check"
+    ]
+  },
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 0
+  },
+  "enforce_admins": false,
+  "restrictions": null
+}
+EOF
+```
+
+`develop` has lighter gates (fast checks only, no mandatory review) to keep velocity high. The full gate is on the `develop → master` promotion PR.