# CONTRIBUTING — канон процесса проекта {{PROJECT_NAME}}

Как ведётся этот репозиторий: где что лежит, как оформлять изменения, как вести документацию.
Канон обязателен и для агентов конвейера, и для людей.

## Где что лежит

| Путь | Содержимое |
|------|-----------|
| код проекта | по код-карте `docs/ARCHITECTURE.md` |
| тесты | прогон: `{{TEST_CMD}}` |
| `.openclaw/agents/` | промпты 6 агентов конвейера (канон структуры — см. ниже) |
| `docs/` | документация (карта — `AGENTS.md`) |
| `docs/work-items/<id>/` | артефакты задач конвейера |
| `.env.example` | карта env-переменных (без секретов) |

## Процесс изменения

1. Задача рождается в Plane (проект `{{PROJECT_NAME}}`, префикс `{{WORK_ITEM_PREFIX}}`).
2. Конвейер ведёт её по стадиям (`docs/PIPELINE.md`); артефакты каждой стадии — в
   `docs/work-items/<id>/` по `docs/_standards/PIPELINE_DOCS.md`.
3. Код едет веткой `feature/{{WORK_ITEM_PREFIX}}-NNN-slug` → PR в `main` → merge только через
   PR-merge (никогда push в `main`).
4. Conventional Commits: `feat(scope):`, `fix(scope):`, `docs(scope):`, `refactor:`, `test:`;
   футер `Refs: {{WORK_ITEM_PREFIX}}-NNN`.
5. Документация обновляется **в том же PR**, что и код (reviewer-gate вернёт PR без неё).
6. `CHANGELOG.md` — запись под `## [Unreleased]` на каждый смысловой PR.

## Промпты агентов (`.openclaw/agents/`)

- Структурный канон: 5 XML-секций в порядке `<context>` → `<task>` → `<deliverables>` →
  `<constraints>` → `<output_format>`; запреты в формате «❌ X → ✅ Y»; `<escalation>` у
  developer/reviewer/tester; машинные verdict-ключи байт-в-байт.
- **Языковая политика:** 5 промптов на русском + `deployer.md` на английском (самый
  safety-critical промпт; en-раскладка минимизирует регресс-поверхность verdict-ключей).
  Отступление от политики — только отдельным ADR этого проекта в `docs/architecture/adr/`.
- Правка промптов = обычный PR с ревью; машинные ключи (`verdict:`, `result:`,
  `staging_status:`, `deploy_status:`, `security_status:`) не переименовывать.

## Документация

- Стандарты (`docs/_standards/`) и скелеты (`docs/_templates/`) — копия живого канона
  оркестратора на момент онбординга; **локально не править** (обновления приходят отдельными PR).
- Сквозные решения — `docs/architecture/adr/adr-NNNN-slug.md`; per-task —
  `docs/work-items/<id>/06-adr/ADR-NNN-slug.md`.
- Маркеры трассировки `{{WORK_ITEM_PREFIX}}-NNN` в коде — по `docs/_standards/TRACEABILITY.md`.

## Секреты

Секреты живут ТОЛЬКО в `.env` на хосте; в гит не коммитятся. Карта переменных — `.env.example`
(дескрипторы без значений). Утечка секрета в коммит = инцидент: ротация ключа обязательна.