gendesign/.claude/rules/git-pr.md

paths
.claude/** .github/** .forgejo/**

Git + PR workflow

Этот файл — manual reference из CLAUDE.md (auto-loaded для .claude/** и .github/** файлов). Если работаешь с code в backend/frontend — также явно открой этот файл при PR-related операциях.

Branch + PR (MANDATORY)

Default workflow — background session через claude --bg:

1. claude --bg --name "feat-<scope>" "task description"
   → supervisor создаёт worktree от forgejo/main автоматически
   (settings worktree.baseRef=fresh, bgIsolation=worktree)
2. Session работает: код → commit → push → mcp__forgejo__create_pull_request
3. PR URL появляется в agent view как row с зелёной/жёлтой/красной ● status dot
4. User делает review через external Claude window (post-push)
5. После merge — `Ctrl+X два раза` в agent view = удаление session + worktree

Foreground workflow (когда нужен интерактив, ad-hoc fixes):

1. git fetch forgejo && git checkout -b feat/<scope> forgejo/main
2. [worker делает код, staged]
3. code-reviewer subagent на staged changes (pre-push)
4. main session: git commit -m "feat(scope): ..."
5. git push -u forgejo feat/<scope>
6. mcp__forgejo__create_pull_request
7. Вернуть PR URL пользователю

Никаких direct push в main. Только через PR merge через Forgejo. gh CLI bypassed (2026-05-16) — все PR-операции через mcp__forgejo__* или curl + $FORGEJO_TOKEN.

Session naming MANDATORY для background spawn: --name "<type>-<scope>-<detail>" (kebab-case, ≤30 chars). Примеры: feat-tradein-cron, fix-nominatim-rate-limit, chore-claude-config. Resume: claude --resume feat-tradein-cron. Filter в agent view: type feat-tradein в input.

Commit messages

• Conventional: feat(scope): ... / fix(scope): ... / refactor/docs/chore/perf
• Imperative: "fix crash" не "fixed crash"
• Body — почему, не что (что видно в diff)
• NO Co-Authored-By: Claude ... — никогда (~/.claude/CLAUDE.md rule)
• Workers (subagents) оставляют staged — main session коммитит
• GenDesign (Mera/Ptica) = full self-service: main/solo session коммитит → пушит → PR → merge сам (см. § Auto-merge policy). balance_platform — наоборот: только stage, commit message в чат, не коммитить/пушить/мержить

PR body template

## Summary
- bullet

## Test plan
- [ ] smoke test

Closes #N

PR: Closes #N — issue закрывается автоматически на merge. Комментарий на issue при PR create: "Working on this in PR #M".

Polling loop

Preferred (background session): dispatch'нул через claude --bg --name "feat-X" → session сама делает PR + monitor. В claude agents row показывает:

• 🟡 yellow ● = waiting on checks/review
• 🟢 green ● = merged
• 🔴 red ● = checks failed
• ⚫ grey ● = draft/closed

Не нужно отдельный polling loop — supervisor сам обновляет row каждые 15s. Peek (Space) для контекста, attach (Enter) если нужен fixup.

Foreground fallback — если работаешь без agents view: Skill loop (self-paced, 90-120s) или background Bash poll:

1. mcp__forgejo__get_pull_request (или curl -sH "$H" "$REPO/pulls/<N>") → читай state, mergeable, head.sha
2. state == merged → stop polling
3. Checks зелёные + mergeable → mcp__forgejo__merge_pull_request (squash + delete branch), с оглядкой на § Auto-merge policy
4. Checks красные → читай лог, fixup commits + push в forgejo feat/<scope> + re-poll
5. Человеческий review с запросом правок → правь, отвечай в треде, re-poll
6. Ничего не изменилось → re-schedule 60s
7. Cap: 30 iter без resolution → stop, ping user.

Auto-merge policy

Self-merge разрешён (2026-06-27, Mera/Ptica). Любая GenDesign-сессия мержит свой PR сама (любой scope), когда checks зелёные. Pre-merge gate: зелёный CI. balance_platform — никогда не мержит (stage only).

Жёсткие исключения (даже при зелёном — НЕ merge, ping human):

• Diff содержит литеральный secret/token/password/credential (40-char hex, API keys, JWT, и т.д.) — security tripwire.
• PR меняет правила самого пайплайна: блок ## Auto-merge policy здесь или Critical rules в CLAUDE.md — self-extending guard (расширение/снятие собственных merge-прав всегда через human, предотвращает bot-loop).

Parallel vs sequential PRs

Default = параллельно, если scope'ы НЕ пересекаются по файлам: каждая задача в своём worktree (git worktree add / isolation:"worktree"), своя ветка, свой PR.

Sequential обязателен когда:

• Пересечение файлов / hot-files: backend/app/api/v1/parcels.py, frontend/src/types/site-finder.ts, OverviewTab/LandTab/MarketTab
• Зависимый стек sub-PR'ов (Foundation → Schema → Workers → Integration): PR N+1 только после merge PR N

Split big issues

Issues ≥ 1.5 day → 3-4 sub-PRs: Foundation → Schema → Workers → Integration. Каждый ~200-500 lines. PR N+1 только после merge PR N.

Бюджет одного subagent-захода и правила эскалации oversized-задач: .claude/rules/delegation.md.

Review workflow (no conflict)

• Pre-push (локально): spawn code-reviewer subagent на staged changes → lint pass (security, correctness, conventions). Блокирует push при 🔴 критикал.
• Post-push (внешнее окно Claude): делает review после PR create, постит комменты от lekss361. Main session НЕ дублирует — только acting on review comments (fixup commits).

Multi-session workflow (Agent View)

Default daily driver: одно окно с claude agents всегда открыто. Все задачи dispatch'аются оттуда через type prompt + Enter — каждая создаёт background session с собственной worktree.

• Параллелизм: 3-5 sessions одновременно (>5 = bottleneck на review, не на Claude per Anthropic метрика)
• Pin (Ctrl+T) для long-running sessions (scraper monitors, deploy watchers) — supervisor не убьёт через 1h idle
• Cleanup: Ctrl+X два раза после merge → session + worktree удалены атомарно
• NEVER parallel sessions на one file — каждая ест в own worktree, last-merge wins (см. § Parallel vs sequential PRs)

Manual git worktree add deprecated — используй claude --bg --name X, supervisor сам isolation делает с baseRef: fresh (свежая ветка от main, не от твоей stale-сессии).

Worktree cleanup (cron weekly): scripts/cleanup-merged-worktrees.sh — удаляет worktrees для merged branches. Запускать вручную или weekly cron.

Запреты

• ❌ git push forgejo main / direct push в main
• ❌ merge PR с литеральным secret в diff ИЛИ PR меняющий правила пайплайна (self-extending guard) — это через human. Иначе self-merge OK (зелёный CI; в pipeline дополнительно approve+SHA)
• ❌ gh pr * — bypassed 2026-05-16, используй Forgejo MCP или curl + $FORGEJO_TOKEN
• ❌ --no-verify / --amend / --no-edit / --force без явного approval
• ❌ @claude в PR comments — plain text only (feedback_no_claude_mentions)
• ❌ Параллельные PR на одни файлы / hot-files (см. § Parallel vs sequential PRs)