# tubev — Git Workflow

Repo для документації / правил / coordination team. Окремо від `backup_<port>/` (це не один з 14 site repos — це наш infra repo).

## Repo info

| | |
|---|---|
| **Origin** | `git@gdev.hserver.cloud:ovtube/vtube.git` (Gitea) |
| **Auth** | SSH key `w4@frontend03.rss.g--o.info` |
| **Default branch** | `main` |
| **Pull strategy** | rebase (`git config --global pull.rebase true`) |

## Worktree layout

| Path | Owner | Permissions |
|------|-------|-------------|
| `/home/w4/goboss/tubev/` | goboss | full (read/write/commit/push) |
| `/home/w4/gocc1/tubev/` | gocc1 (auditor: code) | read-only doc consumption |
| `/home/w4/gocc2/tubev/` | gocc2 (auditor: test) | read-only doc consumption |
| `/home/w4/gocc3/tubev/` | gocc3 (frontend writer) | edit + commit (no push) |
| `/home/w4/gocc4/tubev/` | gocc4 (architect writer) | edit + commit (no push) |

Кожен worktree — самостійний git clone, не symlink. Це дозволяє кожному боту мати свій stage/index незалежно.

## Push policy

**Тільки goboss пушить до origin.** Це enforced через `guard-bash.sh` hook:
- Bot tries `git push` → BLOCKED
- Bot тримає коміти у власному worktree
- goboss робить cherry-pick з bot worktree → push

**Why:** prevent accidental conflicts / force-push / unreviewed pushes до прода. goboss is single point of push authority.

## When to push (default + exceptions)

**Default: push immediately after commit.** Цей repo — docs/coordination, low-risk. Кожен commit = один atomic logical step (P4 atomic-commits global rule). Не накопичуй commits локально.

```bash
# Стандартний цикл:
git pull --rebase
# edit
git add <files>
git commit -m "..."
git push origin main           # ← одразу
```

**Чому push immediately:**
- Bots підтягують через `~/bin/trigger-bots` — швидке рознесення стану
- Conflict window мінімальний (rebase-pull простіший на свіжому стані)
- Audit trail чіткий (кожен commit видимий в origin одразу)
- Не треба пам'ятати "що ще не пушнуто"

**Винятки — НЕ пушити одразу:**

| Situation | Action |
|-----------|--------|
| Multi-step refactor у процесі (3+ commits пов'язані, ще не finalized) | Commit локально, push коли batch complete + code-reviewer agent на повний diff |
| Diff >50 LOC АБО architectural change | Commit локально, **обов'язково** `Agent(superpowers:code-reviewer)` на diff перед push (per `feedback_pre_push_subagent`) |
| Experimental / WIP — developer явно сказав "не пушити поки не скажу" | Commit локально, чекай developer-go |
| Після bot's commit (cherry-pick into goboss worktree) | Push після cherry-pick + reviewer-agent якщо потрібно (workflow B) |

**Не tradeoff'и:** atomic commits + push immediately. Не штучно ділити одну зміну на 5 commits "щоб частіше push'ити". І не штучно групувати незв'язані зміни в один commit "щоб push один раз".

## Workflow patterns

### A. Pure docs change (goboss as author)

```bash
cd ~/goboss/tubev
git pull --rebase                # завжди перед роботою
# ... edit docs/SITES.md ...
git add docs/SITES.md
git commit -m "docs: update site 8112 status"
git push origin main
```

Bots autoматично побачать через `~/bin/trigger-bots` (виконує `git pull` для кожного worktree перед signal'ом).

### B. Bot edits (frontend / architect)

Bot edits in own worktree, commits локально:

```bash
# у gocc3 session:
cd ~/gocc3/tubev
git pull --rebase
# ... edit ...
git add <files>
git commit -m "feat: <change>"
# Write report до ~/comms/gocc3-report.md з commit SHA
# git push — БЛОКУЄТЬСЯ guard-bash.sh
```

goboss reads report, потім:

```bash
cd ~/goboss/tubev
git pull --rebase
# Cherry-pick bot's commit
git fetch /home/w4/gocc3/tubev main
git cherry-pick <SHA>
# Pre-push subagent review (per memory feedback_pre_push_subagent)
# якщо ≥50 LOC або architectural — Agent(superpowers:code-reviewer) на diff
git push origin main
```

### C. Recommendations cadence

`docs/RECOMMENDATIONS.md` — багаточасне джерело backlog. Items НЕ виконуються automatically. goboss нагадує developer'у на session start (1 рядок: `📋 RECOMMENDATIONS: N OPEN ...`). Виконання — тільки коли developer дає `go: реалізуй S1`.

Виконання:
1. goboss отримує `go` → читає item з RECOMMENDATIONS.md
2. Якщо implementation потрібно (більше за trivial) → dispatch на gocc3 (frontend) або gocc4 (architect)
3. Bot робить → commits локально → reports
4. goboss cherry-picks → push
5. Item у RECOMMENDATIONS.md → DONE (move до footer)

## Hooks (active enforcement)

| Hook | Effect |
|------|--------|
| `guard-bash.sh` PreToolUse:Bash | Blocks `git push` для gocc/goorest sessions |
| `guard-bash.sh` PreToolUse:Bash | Blocks Bash write/cp/mv до `/home/nosfortube/` (production source) |
| `guard-readonly.sh` PreToolUse:Edit\|Write | Blocks Edit/Write на `/home/nosfortube/`, `/etc/`, `/var/www/` |
| `auto-signal-goboss.sh` PostToolUse:Write | Auto-signals goboss після bot writes report у `~/comms/` |

## Як додати новий бот / worktree

Якщо буде потрібно gocc5 ABO інший role:

1. Створити worktree: `git clone git@gdev.hserver.cloud:ovtube/vtube.git ~/gocc5/tubev`
2. Додати launcher: `~/bin/gocc5` (skopiyuvati з `~/bin/gocc4` і змінити SESSION/WORK_DIR)
3. Додати у `~/start-devs.sh`, `~/bin/trigger-bots`, `~/bin/clear-bots`, `~/bin/restart-bots`
4. Додати role file: `docs/roles/gocc5-<role>.md`
5. Додати у `CLAUDE.md` Team Coordination таблицю
6. `git push` зміни
7. `~/bin/restart-bots gocc5` — перший запуск

## Testing the cycle

Швидкий smoke test після setup:

```bash
# 1. У goboss зробити дрібну зміну
cd ~/goboss/tubev
echo "" >> docs/SITES.md
git add docs/SITES.md
git commit -m "test: smoke push cycle"
git push origin main

# 2. Bot pull (через trigger-bots для всіх ОА per-bot)
~/bin/trigger-bots

# 3. Verify bot бачить
tmux send-keys -t gocc1 'cd ~/gocc1/tubev && git log --oneline -1' Enter
```

Очікуваний результат: bot's `git log` показує той самий SHA що в origin.

## Troubleshooting

- **Bot "git pull failed"** у `~/bin/trigger-bots`: бот worktree не git repo АБО має локальні зміни що conflicting. `cd ~/<bot>/tubev && git status` — перевір.
- **goboss push rejected**: developer (або інший ботworktree, або інший pусnh source) вже запушив. `git pull --rebase && git push`.
- **Symlink на worktree**: НЕ робити. Кожен bot МАЄ власний clone.