docs: add git workflow rules and update AGENTS.md

Add branching strategy with 4-tier hierarchy (feature_* -> vibes ->
testing -> master), agent guardrails, commit discipline, conventional
commits, rebasing rules, and branch management guidelines.

AGENTS.md

@@ -1,4 +1,5 @@
 ## Documentation for agents
 
+- Git workflow rules: `docs/agents/git-workflow.md`
 - Repo interaction rules: `docs/agents/repo-instructions.md`
 - Domain model & context rules: `docs/agents/domain.md`

docs/agents/git-workflow.md

@@ -0,0 +1,106 @@
+# Git Workflow — Branching Strategy and Rules
+
+## Branch Hierarchy
+
+```
+feature_*  →  vibes  →  testing  →  master
+ (work)     (agent)   (beta)     (stable)
+```
+
+### `master`
+- **Purpose**: Stable, tested, production-ready code. What end-users run.
+- **Who commits**: Human only. Agents **must not** commit or merge here without explicit human instruction.
+- **Requirements**: All tests pass. Code reviewed and approved by human.
+
+### `testing`
+- **Purpose**: Beta-quality code. May contain bugs. Not guaranteed safe.
+- **Who commits**: Human only. Agents **must not** commit or merge here without explicit human instruction.
+- **Requirements**: Human has reviewed `vibes` and approved promotion.
+
+### `vibes`
+- **Purpose**: Agent integration branch. Completed features, bug fixes, and tasks land here for human review.
+- **Who commits**: Agents merge completed feature branches here. Human reviews and either approves (promotes to `testing`) or rejects (sends agent back to feature branch).
+- **Requirements**: Feature branch's tests pass. Feature branch work is complete per task scope.
+
+### `feature_<slug>`
+- **Purpose**: Isolated work branches for a single feature, bug fix, or task.
+- **Who commits**: Agents and humans.
+- **Naming**: `feature_` prefix followed by a short, git-safe slug describing the task (e.g., `feature_add_toast_notifications`, `fix_exit_node_lookup`).
+- **Branch point**: Usually off `master`. If chaining tasks or building on unmerged work, branch off `vibes` or `testing` as appropriate.
+
+## Commit Discipline
+
+Agents must commit frequently, after each self-contained logical unit of work. **Do not batch all changes into a single commit.**
+
+- Commit after each passing test, completed function, or logical change.
+- Each commit should be small, focused, and meaningful on its own.
+- Every commit must be traceable, reversible, and not break existing tests.
+- Granular commits enable easy bisecting, clear history, and precise rollbacks.
+
+## Commit Messages
+
+Use conventional commit format:
+
+```
+<type>: <short description>
+
+<optional body explaining why>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`, `perf`, `ci`, `build`.
+
+Messages must explain **what** changed and **why**. Avoid vague messages like "fix stuff" or "update code".
+
+## Rebasing & Syncing
+
+Before merging a feature branch into `vibes`:
+
+1. Rebase the feature branch onto the latest state of its base branch (`master`, `vibes`, or `testing`).
+2. Resolve any conflicts during rebase.
+3. Verify tests still pass after rebase.
+
+This keeps history linear and avoids unnecessary merge commits.
+
+## Workflow
+
+### Starting Work
+1. Create a new `feature_<slug>` branch from the appropriate base branch (default: `master`).
+2. Push the feature branch to remote.
+3. Implement the feature, bug fix, or task.
+4. Commit frequently (see Commit Discipline above).
+5. Run tests after each commit. Ensure project-wide testing strategy passes.
+
+### Completing Work (Agent)
+1. Rebase feature branch onto latest base branch.
+2. Merge the feature branch into `vibes` (preserve individual commits, do not squash).
+3. Push `vibes` to remote.
+4. Notify human that work is on `vibes` for review. **Stop and wait for human feedback.**
+
+### Human Review
+1. Human reviews `vibes` branch.
+2. **If approved**: Human merges `vibes` → `testing`.
+3. **If rejected**: Human communicates what needs fixing. Agent returns to the feature branch (or creates a new one) to address issues.
+
+### Promoting to Stable
+1. Human validates `testing` branch is ready.
+2. Human merges `testing` → `master`.
+
+## Agent Guardrails
+
+- **NEVER** commit directly to `master` or `testing` without explicit human instruction.
+- **NEVER** merge into `master` or `testing` without explicit human instruction.
+- Always work in a `feature_<slug>` branch.
+- Merge completed work to `vibes`, then stop and wait for human review.
+- Preserve individual commits when merging — do not squash.
+- Rebase feature branches before merging to `vibes` — do not create merge commits.
+
+## Branch Management
+
+- `feature_*` branches may be deleted after merging to `vibes` if no longer needed.
+- If work is rejected from `vibes`, keep the feature branch for iterative fixes.
+- `vibes` should be kept in a mergeable state — do not let it accumulate broken code.
+- Push feature branches to remote for backup and visibility.
+
+## Quick Spikes & Exploration
+
+For quick local exploration or solo spikes, use `.scratch/<feature-slug>/` as documented in `docs/agents/repo-instructions.md`. When spike work becomes real, move it to a proper `feature_*` branch.