docs: enforce PR workflow for ALL changes, no exceptions (#1793)

* docs: enforce PR workflow for ALL changes, no exceptions

Rewrites the "Draft PR First" section to be unambiguous:
- Every file edit (including CLAUDE.md itself) requires a PR
- Explicit list of change types that are NOT exempt
- Step-by-step workflow: branch → change → commit → draft PR → merge
- Finished PRs must be converted from draft and merged immediately

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* remove unnecessary "don't commit to main" warning

Branch protection already prevents direct commits — no need
to restate it as a rule.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add branch-check-first workflow and stash recovery

Agents must check their branch before editing files. If on main,
branch first. If they already have uncommitted changes on main,
stash → branch → unstash.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add PreToolUse hook to block edits on main branch

- Adds a PreToolUse hook that exits 2 (blocks) any Write/Edit when
  the current branch is main, with a clear error message telling the
  agent to create a branch first
- Updates CLAUDE.md to reference the hook and use cherry-pick
  (not stash) for recovering commits made on main by mistake

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: lab <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -347,16 +347,35 @@ refactor.yml        — GitHub Actions workflow that POSTs to the trigger server
 - If a PR can't be merged (conflicts, superseded, wrong approach), close it with `gh pr close {number} --comment "Reason"`
 - Never rebase main or use `--force` unless explicitly asked
 
-### Draft PR First — MANDATORY
+### EVERY Change Goes Through a PR — NO EXCEPTIONS
 
-**NEVER make changes without opening a PR.** Every change MUST go through a draft PR:
+**This is the #1 most important workflow rule.** A PreToolUse hook in `.claude/settings.json` **blocks all Write/Edit calls while on `main`**. If you hit this block:
 
-1. **Create a branch and commit immediately** after the first meaningful change
-2. **Open a draft PR right away** — `gh pr create --draft` after your first commit
-3. **Push incremental commits** as you work — small, frequent commits are better than one big one
-4. **Convert to non-draft when done** — `gh pr ready NUMBER`
+1. **Create a branch** — `git checkout -b descriptive-branch-name`
+2. **Retry your edit** — the hook will allow it now
 
-This applies to ALL work — features, bug fixes, refactors, test additions, config changes. No exceptions. If code was changed, there must be a PR for it.
+**If you already committed to `main` by mistake** — cherry-pick the commits onto a new branch:
+```bash
+git checkout -b descriptive-branch-name
+git cherry-pick main
+```
+
+Then follow this workflow:
+1. **Make your changes** on the branch
+2. **Commit** after the first meaningful change
+3. **Push and open a draft PR** — `git push -u origin HEAD && gh pr create --draft`
+4. **Push incremental commits** as you work
+5. **When done: convert from draft, then merge** — `gh pr ready NUMBER && gh pr merge --squash NUMBER`
+
+**There is NO category of change exempt from this rule:**
+- CLAUDE.md edits → PR
+- Config file tweaks → PR
+- One-line bug fixes → PR
+- Test additions → PR
+- Documentation updates → PR
+- Manifest changes → PR
+
+**A finished PR (tests pass, lint clean) MUST be converted from draft and merged immediately.** Do not leave completed PRs in draft state.
 
 Draft PRs that go stale (no updates for 1 week) will be auto-closed.