From 6ccdebbc48bc0a36de6b8021344f4376b2dc3f51 Mon Sep 17 00:00:00 2001
From: goboss <goboss@frontend03>
Date: Thu, 30 Apr 2026 14:20:55 +0000
Subject: [PATCH] docs: add GIT_WORKFLOW.md, link repo info in CLAUDE.md

- New docs/GIT_WORKFLOW.md: repo info, worktree layout, push policy, workflow patterns
- CLAUDE.md: add repo origin + push policy section
- Doc index updated to include GIT_WORKFLOW.md
---
 CLAUDE.md            |  15 ++++-
 docs/GIT_WORKFLOW.md | 135 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 147 insertions(+), 3 deletions(-)
 create mode 100644 docs/GIT_WORKFLOW.md

diff --git a/CLAUDE.md b/CLAUDE.md
index f96b9bd..a873f40 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,9 +2,17 @@
 
 Multi-site adult tube infrastructure — **frontend-only** scope (templates / CSS / JS). Backend (OpenResty + Lua) — у розробника, не в нашому доступі.
 
-## Сайти
+## Repo
 
-14 портів у `/home/w4/backup_<port>/`. Повна таблиця: **[docs/SITES.md](docs/SITES.md)**.
+- **Origin:** `git@gdev.hserver.cloud:ovtube/vtube.git`
+- **goboss checkout:** `/home/w4/goboss/tubev/`
+- **Bot worktrees:** `/home/w4/<bot>/tubev/` (gocc1-4)
+- **Branch:** `main`
+- **Push policy:** **goboss пушить**. Боти комітять локально → write report → goboss робить review + push. Деталі: **[docs/GIT_WORKFLOW.md](docs/GIT_WORKFLOW.md)**
+
+## Сайти (live, prod source)
+
+14 портів у `/home/w4/backup_<port>/` (mirror з `/home/nosfortube/frontend_<port>/`). Повна таблиця: **[docs/SITES.md](docs/SITES.md)**.
 
 ## Stack
 
@@ -68,8 +76,9 @@ git pull --rebase                # ЗАВЖДИ перед роботою у bac
 
 | Файл | Призначення |
 |------|-------------|
+| **[docs/GIT_WORKFLOW.md](docs/GIT_WORKFLOW.md)** | Repo `vtube`, push process, bot commits → goboss push |
 | **[docs/SITES.md](docs/SITES.md)** | Таблиця 14 портів × домен × cluster × outlier flags |
-| **[docs/SYNC_WORKFLOW.md](docs/SYNC_WORKFLOW.md)** | Як sync.sh працює, 2 парадигми, як додати порт |
+| **[docs/SYNC_WORKFLOW.md](docs/SYNC_WORKFLOW.md)** | Як sync.sh у backup_<port>/ працює, 2 парадигми |
 | **[docs/MODULES.md](docs/MODULES.md)** | Карта `views/modules/*.etlua` × presence × DEL_/test/deprecated flags |
 | **[docs/REFACTOR_RULES.md](docs/REFACTOR_RULES.md)** | Що таке REFACTOR vs CLEANUP vs BUG vs FEATURE |
 | **[docs/RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md)** | Backlog refactor/cleanup/security candidates як рекомендації |
diff --git a/docs/GIT_WORKFLOW.md b/docs/GIT_WORKFLOW.md
new file mode 100644
index 0000000..4cd155b
--- /dev/null
+++ b/docs/GIT_WORKFLOW.md
@@ -0,0 +1,135 @@
+# 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.
+
+## 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.