vtube/docs/GIT_WORKFLOW.md

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 локально.

# Стандартний цикл:
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)

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 локально:

# у 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, потім:

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:

# 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.