# Командная разработка OpenWC

## Цель

Этот workflow позволяет нескольким людям и Codex-агентам работать параллельно, не перезаписывая изменения друг друга и не разрушая архитектурные границы. Единица параллельной работы — не milestone целиком, а ограниченный `work package`.

## Основные правила

1. Каждый агент работает в отдельном clone или Git worktree и собственной ветке.
2. Никто не разрабатывает напрямую в `master`.
3. До изменений задача получает ID, владельца, claim и список затрагиваемых путей.
4. Один work package имеет только одного активного владельца.
5. Общие contracts согласуются до параллельной реализации producers/consumers.
6. Статус milestone и `OPENWC_TARGET_DONE` изменяет только интегратор.
7. Merge выполняется только после handoff, локальных проверок и синхронизации с актуальным `master`.

## Идентификаторы

### Agent ID

Каждый человек/агент выбирает стабильный ID на весь work package:

```text
<human>-<machine>-codex
```

Примеры:

```text
sindo-main-codex
alex-laptop-codex
```

ID записывается в claim, ветке, PR/MR и handoff. Нельзя использовать просто `codex`, потому что таких агентов несколько.

### Work Package ID

```text
<TARGET>-<PROGRAM>-<SHORT-NAME>-<NNN>
```

Примеры:

```text
M01-FND-COORDS-001
M03-RND-SCHEDULER-001
M08-NET-SRP-001
M12-UIA-LUA-SPIKE-001
```

Program codes определены в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md).

## Claim protocol

Предпочтительный канал координации — issue + ранний draft PR/MR на общем Git forge. Если forge недоступен, используется отдельный файл в `coordination/claims/`, который сначала публикуется в общей ветке.

Claim marker:

```text
<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-13 -->
```

Последнее поле — дата истечения claim в UTC. Рекомендуемый срок — 48 часов; владелец продлевает его коротким status update. Истёкший claim нельзя забирать молча: сначала оставить сообщение владельцу и интегратору.

Claim содержит:

- target и work package;
- owner/agent ID;
- outcome и non-goals;
- exclusive paths;
- shared/hotspot paths;
- contracts/schema/format changes;
- dependencies и blockers;
- verification commands;
- expected fidelity evidence.
- documentation deliverables: inline API, module spec, diagrams и source map.

## Ветки и worktrees

Имя ветки:

```text
work/<agent-id>/<target>-<short-name>
```

Пример:

```text
work/sindo-main-codex/m01-coordinate-mapper
```

Начало работы:

```powershell
git fetch origin
git worktree add ..\open-wc-m01 -b work/sindo-main-codex/m01-coordinate-mapper origin/master
```

Правила:

- один worktree принадлежит одному агенту;
- не запускать двух агентов в одном dirty worktree;
- не менять и не удалять чужой worktree;
- generated caches и proprietary data не переносятся commit/cherry-pick;
- перед handoff ветка синхронизируется с актуальным `origin/master`.

## Разделение задач

Хороший work package:

- даёт один наблюдаемый результат;
- принадлежит преимущественно одной подсистеме;
- имеет явные входы/выходы;
- меняет не более одного публичного contract одновременно;
- имеет собственные tests/diagnostics;
- может быть review и merged независимо либо после одной явно указанной dependency.

Плохое разделение:

- «сделать сеть»;
- один агент меняет protocol и UI напрямую;
- два агента одновременно рефакторят один monolithic file;
- задача зависит от незаписанного устного соглашения;
- work package оставляет временный второй источник истины.

## Parallelization patterns

### Contract first

Для cross-layer feature сначала отдельным маленьким work package фиксируются:

- domain types;
- commands/events/read models;
- version/capabilities;
- failure states;
- contract tests.

После merge независимо работают producer и consumers.

Пример:

```text
WP-A: MovementSnapshot contract
  ├─ WP-B: network movement decoder
  ├─ WP-C: gameplay reconciliation
  └─ WP-D: character/camera presentation
```

### Fixtures in parallel

Пока один агент реализует pure logic, второй может готовить:

- synthetic fixtures;
- original-client comparison procedure;
- server-core matrix;
- visual checkpoints;
- documentation/reference analysis.

Fixture agent не изменяет production contract без согласования.

### Adapter split

После merge canonical interface допустимо параллельно реализовать TrinityCore и AzerothCore adapters, если у каждого разные файлы и общая contract suite.

### Hotspot extraction first

Если работа требует одного большого файла, сначала один владелец извлекает стабильный seam. Параллельная работа начинается только после merge seam, а не внутри разных участков монолита.

## Hotspot-файлы

Следующие пути требуют явного указания в claim и согласования с интегратором:

- `project.godot`;
- `AGENTS.md`, `docs/README.md`, `targets/README.md`;
- текущий `targets/[0-9][0-9]-*.md`;
- `RENDER.md`;
- `src/scenes/streaming/streaming_world_loader.gd` до декомпозиции;
- native registration/CMake/GDExtension manifests;
- editor `plugin.cfg` и root plugin lifecycle;
- shared schema/version/format constants;
- dependency lockfiles и submodules.

Два активных work packages не должны редактировать один hotspot. При необходимости интегратор выделяет serial integration window.

## Изменение contracts и форматов

Contract/schema change обязан иметь:

- owner и потребителей;
- backward compatibility или migration;
- old/new fixtures;
- version bump policy;
- rollout order;
- ADR для существенного решения.

Merge order:

1. contract + compatibility layer;
2. producers;
3. consumers;
4. removal deprecated path отдельным work package.

Нельзя одновременно удалить старый API и ожидать, что незамердженная ветка другого агента уже использует новый.

## Commits

Формат заголовка:

```text
<program>(<target>): <imperative summary>
```

Примеры:

```text
fnd(M01): add canonical coordinate mapper
net(M08): decode auth challenge safely
rnd(M03): extract streaming target planner
test(M00): add paired checkpoint manifest
```

Описание commit/PR содержит:

```text
Work-Package: M01-FND-COORDS-001
Agent: sindo-main-codex
Tests: <commands/results>
Fidelity: <evidence/gap>
```

Не смешивать formatting unrelated files, generated artifacts и функциональное изменение в одном commit.

## Handoff protocol

Готовый work package получает marker:

```text
<!-- OPENWC_HANDOFF:READY:M01-FND-COORDS-001:<commit> -->
```

Handoff обязан содержать:

- точный commit/branch;
- outcome и изменённые paths;
- публичные contracts/schema changes;
- verification commands и результаты;
- fidelity evidence/known gaps;
- migration/cache/rebuild requirements;
- unresolved risks;
- recommended merge order;
- updated API/module documentation и перечень diagrams.

Если работа частичная:

```text
<!-- OPENWC_HANDOFF:PARTIAL:M01-FND-COORDS-001:<commit> -->
```

`PARTIAL` не считается завершением и не разрешает ставить target `DONE`.

## Integration protocol

Интегратор:

1. Проверяет claim и отсутствие overlapping ownership.
2. Проверяет diff на unrelated/user changes.
3. Синхронизирует branch с `master` без уничтожения чужой истории.
4. Запускает package verification и затронутые общие gates.
5. Проверяет docs, migrations, cache versions и fidelity statement.
6. Проверяет documentation gate из `docs/DOCUMENTATION_STANDARD.md`: API docs, inputs/outputs, diagrams, ownership и recovery.
7. Проверяет coding gate из `docs/CODING_STANDARD.md`: ясные имена, KISS, отсутствие premature abstractions и скрытого data flow.
8. Merge/squash выполняет в соответствии с историей work package.
9. После merge запускает post-merge smoke.
10. Закрывает claim marker-ом:

```text
<!-- OPENWC_INTEGRATION:ACCEPTED:M01-FND-COORDS-001:<merge-commit> -->
```

Только после интеграции всех обязательных work packages интегратор обновляет target Evidence/status.

## Конфликты

При обнаружении overlapping edits агент должен остановить изменение затронутого файла и связаться с владельцем. Запрещено:

- разрешать конфликт через слепое `ours/theirs`;
- копировать чужой файл поверх своего;
- делать `reset --hard` или checkout чужих изменений;
- «временно» дублировать contract без migration plan.

Порядок разрешения:

1. определить semantic owner;
2. выбрать merge order;
3. первый владелец публикует минимальный contract/seam;
4. второй rebase и адаптирует свою ветку;
5. integration tests подтверждают совместимость.

## Status updates и stale work

Владелец обновляет claim после значимого результата или не реже срока lease. Status краткий:

```text
State: active | waiting | ready | partial
Done: ...
Next: ...
Blocked by: ...
Touched paths: ...
```

Если работа прекращена, claim явно освобождается. Незавершённую ветку не удаляют до handoff с описанием пригодных commits и известных проблем.

## Минимальная схема для двух разработчиков

- Один человек назначается интегратором текущего milestone.
- Второй берёт work package без пересечения файлов либо готовит fixtures/reference/adapter.
- Роль интегратора можно менять после каждого milestone.
- Перед началом дня оба выполняют `git fetch` и сверяют claims/draft PRs.
- Перед merge второй агент не начинает работу поверх непроверенного commit, если dependency не опубликована как contract branch.

Пример для M01:

```text
Developer A / integrator:
  M01-FND-COORDS-001 — coordinate types and mapper

Developer B:
  M01-QAR-COORD-FIXTURES-001 — known ADT/server points and tests

После merge contract:
  A — StreamingFocus migration
  B — placement/SQL conversion audit
```

## Автоматическая проверка

Перед handoff и merge запускать:

```powershell
.\tools\verify_coordination.ps1
.\tools\verify_documentation.ps1
```

Первая проверка требует ровно один `ACTIVE` numbered target, соответствие `Current target`, валидные и уникальные fallback claim markers. Вторая проверяет обязательные documentation files, структуру module specs, наличие data-flow diagram и относительные ссылки. Истёкший claim выдаёт warning и требует человеческого решения, но не удаляется автоматически.
