Git hygiene & enforcement

Practical rules to avoid local/origin drift and accidental pushes to protected branches. Longer planning history: ../GIT-WORKFLOW.md.

Companion: Branching · ../BRANCH-PROTECTION-BASELINE.md

---

Daily hygiene

On main or develop:

git fetch origin
git pull --ff-only origin develop   # or main

If ff-only fails and you have no local-only commits you need:

git fetch origin
git reset --hard origin/develop     # or origin/main

After a PR merges: delete the local feature branch.

git branch -d feature/TASK-62-git-process-docs

---

Recovery: ahead N / behind M on protected branch

If git status -sb shows ## main...origin/main [ahead N, behind M] with N > 0:

1. Working tree clean? git status --short → empty.
2. Inspect local-only commits: git log origin/main..HEAD --oneline
   If they are already squash-merged on origin (PR markers), they are safe to drop.
3. Snap: git fetch origin && git reset --hard origin/main
4. Verify: no ahead/behind counts.

Do not git pull (merge) or pull --rebase a large divergent main — that replays squash-duplicates and creates conflict storms.

---

Commit messages

• Conventional Commits
• PR title becomes the squash message: type(scope): summary

---

Enforcement tiers

Tier	What	Status
1 — Agents	AGENTS.md + Copilot instructions point at docs/git/	Rolling out (Epic G)
2 — Local hooks	Block direct commit/push to main; pull.ff only	Planned (see legacy GIT-WORKFLOW)
3 — Branch protection	Repo rulesets: PR required, linear history, squash-only, admin bypass	Active — bz-protect-canonical
4 — CI	Reject PR branch names without TASK-{id}	Active — branch-name-guard workflow

---

Agent rules (Tier 1)

Coding agents must:

1. Refuse to invent feature/* branches without a GitHub Issue number.
2. Use feature/TASK-{id}-{slug} (or allowed prefixes).
3. Not commit directly to main / develop.
4. Link PRs to issues (Closes #NNN).