diff --git a/PRD Drafts/git-repo-setup-peer-review.md b/PRD Drafts/git-repo-setup-peer-review.md new file mode 100644 index 0000000..3e82af3 --- /dev/null +++ b/PRD 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///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`.