# 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`.