itsgoin/CONTRIBUTING.md

# Contributing to ItsGoin

This document defines how all contributors — human and Claude Code instances — work on this repository. It is authoritative policy; follow it regardless of whether you are the primary context-holder or a newly-joined contributor.

---

## Status

**Adopted: 2026-04-23.** The workflow below is policy, but some of its prerequisites are still being stood up. Until the Phase 0 checklist at the bottom of this file is complete, certain rules that reference infrastructure (e.g. "wait for CI to pass") are aspirational. The **branching, PR, and review rules are in effect immediately**. See the Phase 0 section for current state.

---

## Core rules (all contributors)

### Branching

- **Never commit or push directly to `master`.** Master is only updated through merged PRs.
- Before starting work, create a branch tied to a Forgejo issue:
  ```
  git checkout -b <type>/<issue-number>-<short-desc>
  ```
  - Types: `feat`, `fix`, `refactor`, `chore`, `docs`
  - Example: `feat/142-pq-key-exchange`, `fix/89-anchor-handshake-timeout`
- One branch per issue. If there's no issue yet, create one first.
- Keep branches short-lived — hours to a couple of days. Long branches accumulate conflicts.

### Commits

- Commit early, commit often. WIP commits are fine; squash before PR if you want a cleaner history.
- Use imperative mood: "Add retry logic" not "Added retry logic".
- Reference the issue in the message: `Fix anchor handshake timeout (#89)`.

### Staying current with master

Before pushing, always:
```
git fetch origin
git rebase origin/master
```

Resolve conflicts locally, then push. If a rebase goes sideways, `git rebase --abort` safely returns you to where you started.

### Pushing and opening PRs

- Push to your own branch: `git push origin <branch-name>`.
- Open a PR in Forgejo targeting `master`. Fill in the description: what, why, how tested.
- Link the Forgejo issue.
- Wait for CI to pass (once CI exists — see Phase 0).
- **Jr PRs**: wait for Lead review before merging. The Lead is the review.
- **Lead PRs**: self-merge permitted after self-review. The Lead carries the most project context and the buck stops there; failure mode is "take steps back and retry," which Scott accepts as the cost of removing PR-review bottlenecks from the critical path.

### Force-pushing

- **Never** use `git push --force`.
- `git push --force-with-lease` is acceptable *only* on your own feature branch and *only* when you are its sole contributor.
- Never force-push to `master` or any shared branch.

### Absolutely forbidden

- `git push --force` (without `--with-lease`)
- `git reset --hard` on a branch containing uncommitted work you didn't author
- Rebasing a branch another contributor is committing to
- **Jr contributors**: merging your own PR (Lead review is required)
- Committing secrets, credentials, API keys, or large binaries
- Bypassing `.deploy-creds` into git history (it's .gitignored; keep it that way)

### Before any destructive operation

Always check:
```
git status
git branch --show-current
git log -5 --oneline
```

Know what branch you're on and what you'd lose before you lose it.

---

## Session protocol

### Starting a session

1. `git fetch origin`
2. Read the latest `sessions.md` entries to understand recent state.
3. Pick or confirm your assigned Forgejo issue. Verify no other contributor is actively working it.
4. Create your branch from current `master`.
5. Append to `sessions.md`: timestamp, your instance identifier, issue number, branch name.

### Ending a session

1. Commit any WIP with a clear message.
2. Push your branch if it's in a shareable state.
3. Update `sessions.md` with what you completed, what's pending, blockers, and your exact stopping point.
4. If work is ready, open the PR before signing off.

---

## Reviewing PRs

- **Jr PRs are reviewed by the Lead.** This is the critical check — a Lead who knows the codebase deeply is best positioned to catch the issues that a merge of foreign code could introduce (compile breaks across files, invariant violations, mis-scoped changes).
- **Lead PRs are self-reviewed by the Lead.** Scott is not in the PR review path; see Amendment 6 below.
- Focus on intent and design — CI handles formatting, tests, and lints.
- Approvals should include a brief "why." Change requests should be specific.
- Scott is the tiebreaker for genuine disagreements with the Lead's call, not the default reviewer.

---

## Role-specific notes

### Primary contributor (highest project context — "Lead")

- The Lead carries the most project context. Self-merge authority is explicit: review carefully, merge, move on. Buck stops here.
- You're often the best source for "why is this code this way?" — write that reasoning into PR reviews of Jr work so the knowledge spreads.
- Accept that some decisions will need reversion later. Scott's posture: *"the risk of failure is generally taking steps back and trying again"* — preferable to blocking on a review step that has no effective reviewer in the current single-senior era.

**Lead role responsibilities (current Lead = Scott's Claude):**

- Check the PR queue on session start and at natural stopping points. Pick up any Jr PR there. Pull the branch, run `cargo check --workspace` + `cargo test -p itsgoin-core`, read for semantic issues that clean-merged textually but may break compile / violate invariants / change behavior subtly.
- Take dev work on **senior-category** issues only: protocol, crypto, concurrency / locking, `receive_post` gate changes, identity/network split, architectural refactors, production hotfixes.
- Own the full build + deploy pipeline: CLI + AppImage + APK on Linux; signing; uploads; anchor swap; release-announcement publish.
- Maintain `reference_build_deploy.md`, `AGENTS.md`, and your own `sessions.md` entries for any active branch.

**Lead does NOT:**

- Track who is working on what (Scott coordinates / watches alignment).
- Authorize anyone for anything (Scott authorizes Jr assignments).
- Answer Jr questions unprompted (Scott pings you with specific ones when needed).
- Decide Jr- vs senior-category scoping (Scott triages).
- Windows installer builds, iOS/Mac builds (handed off to environment-bound builders).
- Wait for Scott's approval to merge own PRs (self-merge authority is explicit).

### Secondary / newly-joined contributors ("Jr")

- Before writing code, read `AGENTS.md`, `CONTRIBUTING.md` (this file), and the last several `sessions.md` entries.
- If unsure whether an approach fits the project's existing patterns, ask Scott to route the question to the Lead *before* investing in the implementation.
- Defer to established architectural decisions unless you have a specific, articulable reason to revisit them. If you want to revisit, open a discussion issue first — not a PR.

---

## Amendments to the base workflow (2026-04-23)

These adjust the generic contributor doc to ItsGoin's specific operational realities. They are policy, not suggestions.

### 1. Hotfix carve-out

For **true production-down scenarios** the Lead retains direct-to-master authority, bypassing branch + PR + review. Scope is narrow and specific:

- Anchor won't start / crash loop
- TLS handshake broken for all clients
- Storage corruption / migration failure
- Active security incident (e.g. key compromise, auth bypass)

Requirements when the carve-out is exercised:

1. Commit message must begin with `hotfix:` and clearly describe the production symptom.
2. A retrospective PR must be opened within 24 hours for review-after-the-fact. Purpose is audit trail + sanity check, not gating.
3. Logged in `sessions.md` with timestamp + what was broken + what was changed.

This does **not** apply to: routine bugs, feature requests flagged urgent, UX polish, or any case where the network is operational.

### 2. Build trigger: partnered go/no-go

Builds and deploys are a partnership between Lead and Scott. Lead proposes ship / hold based on what's ready; Scott confirms or redirects. There is no rolling auto-deploy on merge and no N-PRs-threshold. Either party can initiate the conversation ("ready to ship X" / "let's hold until Y lands"), and the other can agree, counter, or surface a concern.

### 3. Review SLA: Lead pulls from queue at stopping points

The Lead checks the Jr PR queue at session start and at natural stopping points between their own tasks. No hard time budget. Scott doesn't route PRs to the Lead — they appear in Forgejo and the Lead picks them up. The only exception: if a Jr is blocked AND Scott flags it urgent, the Lead preempts current work.

### 4. Re-evaluation triggers for the Lead role

The current Lead role is "senior-category dev + reviewer + build/deploy owner." Shift to pure-reviewer/integrator (drop the dev hat) if any of these hold:

- 5+ concurrent Jr agents active
- Lead review queue regularly runs past 1-day latency
- Lead finds themselves rewriting Jr PRs in review rather than commenting
- Scott's coordination / routing load hits his limit

These are triggers for reassessment, not automatic policy flips.

### 5. Secrets and credentials

- `.deploy-creds` is `.gitignore`d. Never commit it.
- Each contributor instance gets its own Forgejo account + SSH key (see Identity section below). Never share credentials.

### 6. Scott's role + Lead self-merge authority

Scott's role in the day-to-day workflow is:

- **Contributor alignment watcher.** Scott maintains awareness of what each contributor is working on and catches drift, scope creep, or cross-purposes early — at the contributor level, not the PR level. When he sees alignment issues, he redirects the contributor directly.
- **Ship partner.** On build + deploy decisions, Scott is the Lead's partner (see Amendment 2). Not an authorizer standing between the Lead and production.
- **Tiebreaker on disagreements.** Where the Lead and a Jr (or a future second senior) disagree on architectural direction, Scott is the final call.

Scott is **not** in the PR review critical path. He does not route PRs, does not approve merges, does not sign off on individual changes. He trusts the Lead's code-review judgment and the Jr contributor's aligned intent.

**Lead self-merge is authorized by default.** The Lead reviews their own PR, merges, moves on. The explicit tradeoff Scott has named: *"the risk of failure is generally taking steps back and trying again."* That's preferred over a gating step that has no effective reviewer in the current single-senior era. The Lead carries the context and the accountability.

---

## Identity

Each instance has its own Forgejo account and SSH key. Set local Git config per repo:
```
git config user.name "Claude (<role-or-identifier>)"
git config user.email "<your-account>@<domain>"
```

- Never use another instance's credentials.
- Never share your own.
- Commit authorship is how we audit and debug multi-agent work. Keep it clean.

---

## When in doubt

Stop and ask. A paused session is cheap; overwritten work is expensive. If something about the repo state looks unexpected (unfamiliar commits, a branch in a weird position, a conflict you don't understand), do not "fix" it autonomously — note it in `sessions.md` and surface it to Scott.

---

## Phase 0 checklist — prerequisites still pending

These must be true before the full workflow above is operational. Until each is checked, the corresponding rule is aspirational and contributors should route around it by asking Scott.

- [ ] Forgejo CI stood up (minimum: `cargo check --workspace` + `cargo test -p itsgoin-core` on push to any branch and on PR).
- [ ] Branch protection enabled on `master`: require PR, require 1 passing review, require CI green.
- [x] `sessions.md` exists in the repo root (this PR creates it).
- [ ] Second Forgejo account created for Jr Claude(s) with its own SSH key configured.
- [x] `AGENTS.md` exists in the repo root (this PR creates it; cross-agent session guide — see security banner at top of that file).

Note on `CLAUDE.md` specifically: it is `.gitignore`d at the repo root because historically AI agents (including Claude) have dropped credentials into a `CLAUDE.md`-style file and those leaks are catastrophic in git history. `AGENTS.md` replaces it as the committed contributor-facing guide, with an explicit security banner forbidding credential writes. If a Claude instance needs a local scratch file, it can still use `CLAUDE.md` in the working copy — just knowing it will never reach the repo.

Current state as of 2026-04-23: **this PR** (`chore/workflow-adoption`) creates `CONTRIBUTING.md`, `AGENTS.md`, and `sessions.md`. The remaining items (CI + branch protection + Jr account) are follow-up work Scott will coordinate.

Until CI exists, the Lead's `cargo check --workspace` + `cargo test -p itsgoin-core` during PR review serves as the CI gate.