From 3518f0f2a2b9f818190ec845fe497d2700a9d90e Mon Sep 17 00:00:00 2001
From: Alexander Whitestone <alexpaynex@gmail.com>
Date: Tue, 7 Apr 2026 05:03:45 -0400
Subject: [PATCH] feat: [QA][POLICY] Branch Protection + Mandatory Review
 Policy for All Repos (#918)

Refs #918
Agent: groq
---
 .github/CODEOWNERS               | 16 ++++++++++++
 .github/pull_request_template.md | 15 +++++++++++
 CONTRIBUTING.md                  | 44 ++++++++++++++++++++++++++++++++
 DEVELOPMENT.md                   | 23 +++++++++++++++++
 4 files changed, 98 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index b03e37f..e7e6bd2 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -14,3 +14,19 @@ timmy-config/ @perplexity
 
 # Owner gates
 hermes-agent/ @Timmy
+# CODEOWNERS - Mandatory Review Policy
+
+# Default reviewer for all repositories
+* @perplexity
+
+# Specialized component owners
+hermes-agent/ @Timmy
+hermes-agent/agent-core/ @Rockachopa
+hermes-agent/protocol/ @Timmy
+the-nexus/ @perplexity
+the-nexus/ai/ @Timmy
+timmy-home/ @perplexity
+timmy-config/ @perplexity
+
+# Owner gates
+hermes-agent/ @Timmy
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 1870f96..755dcab 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -48,3 +48,18 @@ Briefly describe the changes in this PR.
 ## Specialized Owners
 - [ ] @Rockachopa (for agent-core)
 - [ ] @Timmy (for ai/)
+## Pull Request Template
+
+### Summary
+- [ ] Describe the change
+- [ ] Link to related issue (e.g. `Closes #123`)
+
+### Checklist
+- [ ] Branch protection rules respected
+- [ ] CI/CD passing (where applicable)
+- [ ] Code reviewed by @perplexity
+- [ ] No force pushes to main
+
+### Review Requirements
+- [ ] @perplexity for all repos
+- [ ] @Timmy for hermes-agent changes
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e5a5ff6..b4bdb6f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -299,3 +299,47 @@ All repositories enforce:
 CODEOWNERS
 ```text
 <<<<<<< search
+# Contribution & Code Review Policy
+
+## Branch Protection Rules
+All repositories must:
+- ✅ Require PR for merge
+- ✅ Require 1 approval
+- ✅ Dismiss stale approvals
+- ⚠️ Require CI to pass (where exists)
+- ✅ Block force push
+- ✅ block branch deletion
+
+## Review Requirements
+- 🧑 Default reviewer: `@perplexity` for all repos
+- 🧑 Required reviewer: `@Timmy` for `hermes-agent/`
+
+## Workflow
+1. Create feature branch from `main`
+2. Submit PR with clear description
+3. Wait for @perplexity review
+4. Address feedback if any
+5. Merge after approval and passing CI
+
+## CI/CD Requirements
+- All main branch merges require:
+  - ✅ Linting
+  - ✅ Unit tests
+  - ⚠️ Integration tests (pending for the-nexus)
+  - ✅ Security scans
+
+## Exceptions
+- Emergency hotfixes require:
+  - ✅ @Timmy approval
+  - ✅ Post-merge documentation
+  - ✅ Follow-up PR for full review
+
+## Abandoned PRs
+- PRs inactive >7 days: 🧹 archived
+- Unreviewed PRs >14 days: ❌ closed
+
+## CI Status
+- ✅ hermes-agent: ci active
+- ⚠️ the-nexus: ci runner dead (see #915)
+- ✅ timmy-home: No ci
+- ⚠️ timmy-config: Limited ci
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..03adc3a
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,23 @@
+# Development Workflow
+
+## Branching Strategy
+- Feature branches: `feature/your-name/feature-name`
+- Hotfix branches: `hotfix/issue-number`
+- Release branches: `release/x.y.z`
+
+## Local Development
+1. Clone repo: `git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus.git`
+2. Create branch: `git checkout -b feature/your-feature`
+3. Commit changes: `git commit -m "Fix: your change"`
+4. Push branch: `git push origin feature/your-feature`
+5. Create PR via Gitea UI
+
+## Testing
+- Unit tests: `npm test`
+- Linting: `npm run lint`
+- CI/CD: `npm run ci`
+
+## Code Quality
+- ✅ 100% test coverage
+- ✅ Prettier formatting
+- ✅ No eslint warnings
-- 
2.43.0