Add Part 10 — Git workflow

- Commit message format (imperative mood, 50 char subject, area prefixes) - Commit early/often philosophy - When to amend vs. new commit - Push guidelines (never force main, destructive operations need approval) - Repository hygiene (what to commit, .gitignore maintenance) - Signed commits noted for future
2026-04-08 13:53:52 -04:00 · 2026-04-08 13:53:52 -04:00 · 00f21464c3
parent 199495cdd8
commit 00f21464c3
1 changed files with 101 additions and 0 deletions
--- a/CLAVITOR-PRINCIPLES.md
+++ b/CLAVITOR-PRINCIPLES.md
@ -1180,4 +1180,105 @@ The feature will mature separately from these architectural principles.

 ---

+## Part 10 — Git workflow
+
+### Commit philosophy
+
+**Commit early, commit often.** A commit is a save point, not a publish event.
+- One logical change per commit — don't mix bug fix + refactoring + new feature
+- If you can't explain the commit in one sentence, it's too big — split it
+- Work-in-progress commits are fine locally; clean up before sharing
+
+### Commit message format
+
+```
+<subject>: <what changed>
+
+<body>: <why it changed> (optional but encouraged)
+
+<footer>: <references> (issue #123, fixes, etc.)
+```
+
+**Subject line rules:**
+- Imperative mood: "Add rate limiter" not "Added rate limiter"
+- No period at end
+- Max 50 characters (GitHub truncates at 72)
+- Prefix with area: `api:`, `lib:`, `web:`, `crypto:`, `docs:`
+
+**Good:**
+```
+api: add per-agent IP whitelist middleware
+
+Implements Threat C defense: first contact fills whitelist,
+subsequent requests rejected if IP not in list. Supports CIDR
+and FQDN in addition to exact IPs.
+
+Fixes #456
+```
+
+**Bad:**
+```
+changes
+
+lots of changes to the code including some fixes and also 
+refactored the handler and added new feature for agents
+```
+
+### When to commit vs. amend
+
+**Amend** (rewrite history) for:
+- Fix typo in commit you just made
+- Add file you forgot to stage
+- Improve commit message
+
+**New commit** for:
+- Any change that has been pushed (even to your own branch)
+- Changes that logically separate from previous work
+- Anything another developer might have based work on
+
+### Push guidelines
+
+**Never force push to `main` or `master`.** Ever.
+
+**Branch workflow:**
+1. Create feature branch: `git checkout -b feature/agent-lockdown`
+2. Commit work-in-progress freely
+3. Before push: `git rebase -i main` to clean up (squash "fix typo" commits)
+4. Push branch: `git push -u origin feature/agent-lockdown`
+5. Open PR (when we have CI), or merge with `--no-ff` for feature visibility
+
+**Destructive operations require explicit approval:**
+- `git reset --hard`
+- `git push --force` (any branch)
+- `git filter-branch` or `git filter-repo`
+- Branch deletion with unmerged commits
+
+State: "About to [destructive operation] on [branch]. This will [effect]. 
+Alternative: [safer option]. Proceed?"
+
+### Repository hygiene
+
+**What we commit:**
+- Source code
+- Generated code that's not reproducible (rare)
+- Documentation
+- Configuration templates (`.env.example`, not `.env`)
+
+**What we DO NOT commit:**
+- Secrets (keys, passwords, tokens)
+- Build artifacts (`*.o`, `*.a`, binaries)
+- Dependencies (vendor them or use go.mod)
+- User data, vault files, logs
+
+**`.gitignore` maintenance:**
+- If a file is generated or contains secrets, add it to `.gitignore`
+- Review `git status` before every commit — nothing should surprise you
+
+### Signed commits (future)
+
+When we add contributor access beyond core team, signed commits (SSH or GPG)
+will be required. All commits must be verifiable.
+
+---
+
 *Foundation First. No mediocrity. Ever.*