draft: Git Repo Setup & Peer Review PRD (v1)

2026-06-03 10:02:20 -04:00
parent d6ed7f6ead
commit dbeaeab60d
1 changed files with 145 additions and 0 deletions
--- a/Drafts/git-repo-setup-peer-review.md
+++ b/Drafts/git-repo-setup-peer-review.md
@@ -0,0 +1,145 @@
+# Git Repo Setup & Peer Review PRD
+
+**Status:** Draft — Pending Commander Bobby Review
+**Author:** Artemis
+**Date:** 2026-06-03
+
+---
+
+## 1. Purpose & Scope
+
+This PRD defines the **standard Git repository setup** for all Iron Legion Labs projects hosted on Gitea. Every new repo — whether fleet config, documentation, or service-specific — must follow this pattern so that **drafts live in forks/PRs** and **canonical docs live on protected branches**.
+
+**In scope:**
+- Branch protection rules (mandatory)
+- Fork + PR workflow for documentation and PRDs
+- Credential/token management for CI/automation
+- Gitea API token reference for Artemis automation
+
+**Out of scope:**
+- Code review style guides (covered per-project)
+- CI/CD pipeline definitions (separate PRDs)
+
+---
+
+## 2. Success Criteria
+
+| # | Criterion | How Verified |
+|---|-----------|-------------|
+| 1 | Every new repo has `main` branch protected on creation | API query or UI inspection |
+| 2 | Direct push to `main` is blocked without PR + review | Attempt push, expect 403 or pre-receive hook rejection |
+| 3 | All PRDs and docs go through fork → PR → review → merge | Git log shows merge commits from PRs |
+| 4 | Artemis can automate via Gitea API using stored R/W token | `curl -H "Authorization: token ..."` returns 200 |
+
+---
+
+## 3. Gitea Token Reference
+
+Tokens are stored in **two places** depending on scope:
+
+| Token | Purpose | Storage | Scope |
+|-------|---------|---------|-------|
+| `gitea_deploy_token` | Read-only for ansible-pull nodes | `/home/jarvis/.ansible/secrets/deploy_token` | repo:read |
+| `gitea_rw_token` | Read-write for Artemis automation | `/home/jarvis/.ansible/secrets/deploy_token` | repo:write, organization |
+
+**Both are also mirrored to:**
+`~/.hermes/credentials/fleet.env` (mode 600) for runtime access by Artemis.
+
+---
+
+## 4. Branch Protection Rules (Mandatory for Every Repo)
+
+Apply these rules to the `main` branch on repo creation:
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| Enable branch protection | ✅ ON | Prevents accidental force-push |
+| Require pull request reviews | ✅ ON, minimum **1** approver | Ensures human review |
+| Dismiss stale approvals | ✅ ON | Re-review after new commits |
+| Block merge without approval | ✅ ON | No self-merge loophole |
+| Enable push whitelist | ✅ ON, deploy keys only | CI can push; humans cannot |
+| Require status checks | ❌ OFF (until CI is configured) | No false blocking |
+
+**API method** (for Artemis automation):
+```bash
+curl -sk "https://gitea.nb.bobbysh.me/api/v1/repos/<org>/<repo>/branch_protections" \
+  -H "Authorization: token $GITEA_RW_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "branch_name": "main",
+    "required_approvals": 1,
+    "enable_approvals_whitelist": false,
+    "enable_merge_whitelist": false,
+    "enable_push": true,
+    "enable_push_whitelist": true,
+    "push_whitelist_deploy_keys": true,
+    "enable_pr": true
+  }'
+```
+
+**UI method** (for manual setup):
+1. Repo → Settings → Branches → `main` → **Add Protection Rule**
+2. Check the boxes above → Save
+
+---
+
+## 5. Draft → Canon Workflow
+
+```
+┌─────────────┐      ┌──────────────┐      ┌──────────────┐
+│   PRD Draft │ ───▶ │   Fork/PR    │ ───▶ │   Review     │
+│   PRD Drafts/│      │   (any dev)  │      │   (Bobby)    │
+└─────────────┘      └──────────────┘      └──────┬───────┘
+                                                   │
+                           ┌───────────────────────▼───────┐
+                           │   Approved → merge to main   │
+                           │   Move file: PRD Drafts/ →   │
+                           │   PRDs/ (canonical)          │
+                           └──────────────────────────────┘
+```
+
+### For Artemis (automation):
+- Drafts are written to `PRD Drafts/` directly during active work sessions
+- Bobby approves → Artemis moves to `PRDs/` in a follow-up commit
+- No PR needed for Artemis-authored drafts (Bobby reviews inline)
+
+### For F.R.I.D.A.Y. / human contributors:
+- Fork the repo
+- Push draft to fork branch
+- Open PR against `main`
+- Bobby (or designated reviewer) approves
+- Merge → file lands in `PRDs/`
+
+---
+
+## 6. Repo Setup Checklist
+
+Use this for every new repo:
+
+- [ ] Create repo under `Iron-Legion/` org
+- [ ] Initialize with `main` branch only (delete `master` if auto-created)
+- [ ] Apply branch protection rules (Section 4)
+- [ ] Add `README.md` with scope statement
+- [ ] Add `.gitignore` for secrets/build artifacts
+- [ ] If CI/automation needed: register deploy key or token
+- [ ] Document in `Iron-Legion/documentation` fleet registry
+
+---
+
+## 7. Open Questions
+
+1. **Should we create a Gitea org-level default branch protection template?** (Applies to all new repos automatically)
+2. **Should F.R.I.D.A.Y. also store the R/W token?** (Currently only Artemis has it in `fleet.env`)
+3. **Do we want a CODEOWNERS file** in each repo to auto-assign reviewers?
+
+---
+
+## 8. Fleet Credential Store Update
+
+Added to `~/.hermes/credentials/fleet.env`:
+```
+GITEA_DEPLOY_TOKEN=226c3ef38eb35914ae6b647803c2e597f66f28cb
+GITEA_RW_TOKEN=968e86d51ab9b6b2a3eb5e97b391ce8c6534ec2d
+```
+
+Source of truth remains `/home/jarvis/.ansible/secrets/deploy_token`.