From 568335a643c799d9aaecff5fc16041d66925541f Mon Sep 17 00:00:00 2001 From: estorozhenko Date: Sun, 13 Sep 2026 11:12:21 +0000 Subject: [PATCH] docs(governance): enforce OpenSpec workflow for all changes; openspec: enforce-openspec-workflow --- AGENTS.md | 48 +++++++++++++ README.md | 15 ++++ openspec/config.yaml | 1 + .../gotosocial/project-governance/spec.md | 68 +++++++++++++++++++ 4 files changed, 132 insertions(+) create mode 100644 AGENTS.md create mode 100644 openspec/specs/gotosocial/project-governance/spec.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c346121 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS.md — Правила для AI-агентов (Hermes) + +## ЖЁСТКОЕ ТРЕБОВАНИЕ: все изменения — через OpenSpec + +**ЛЮБОЕ изменение проекта** (код, docker-compose.yml, config, системные +юниты, документация, статусы) **ОБЯЗАНО** проходить через OpenSpec-воркфлоу: + +1. `/openspec-propose <имя-изменения>` — создать change + (proposal.md → specs/ delta → design.md → tasks.md). +2. `/openspec-apply-change <имя>` — реализовать задачи из tasks.md + (с реальной верификацией каждой). +3. `/openspec-archive-change <имя>` — влить delta в main specs + (`openspec/specs/`), после `openspec validate`. + +**Запрещено** (без исключений): + +- ❌ Править docker-compose.yml / config.yaml / код / юниты напрямую + без openspec-change. +- ❌ Коммитить изменения без соответствующего openspec-change + (коммит = `feat/fix(...): ...; openspec: `). +- ❌ «Мелкие правки» в обход openspec: статус-файлы, README, доки — + тоже изменения, оформляются так же (допускается `skip_specs: true` + для чисто документационных правок). + +**Исключения**: только по явной команде пользователя +(«сделай в обход openspec» / подтверждение на прямой фикс). + +## Рабочий процесс + +- Прочитать перед действиями: `STATUS.md`, `PRD.md`, `README.md`, + `TODO.md`, `openspec/specs/**/spec.md`. +- Верификация каждой задачи — реальная команда (curl, docker ps, + systemctl status), не предположение. +- Секреты: в `.env`, в git не попадают. +- Рестарт сервисов — только извне (SSH sudo systemctl restart). +- Git: маленькие коммиты; источник истины gitverse.ru. + +## Текущая спецификация + +- `openspec/specs/gotosocial/` — trusted-proxies, webfinger-and-registration, + webclient-and-clean-footer, smtp-email. + +## Справочник essentials + +- Контейнер: `gotosocial` (image superseriousbusiness/gotosocial:0.22.1) +- Данные: `/opt/gotosocial/data/` (sqlite.db + storage/) +- Порт: 8080 внутри, Caddy vps02 → 10.8.0.2:8080 +- SMTP: smtp.jino.ru:587, `GTS_SMTP_FROM`, `GTS_SMTP_USERNAME` (соц@dedinit.ru) \ No newline at end of file diff --git a/README.md b/README.md index 332b10f..cedb933 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,21 @@ Internet ──► vps02 87.242.100.206 (Caddy 2, host net) └── openspec/ # OpenSpec-воркфлоу (changes/deploy-gotosocial) ``` +## Правила изменений (обязательно) + +**Все изменения проекта** (код, docker-compose.yml, config.yaml, документы, +статусы) проводятся **только через OpenSpec-воркфлоу**: + +1. `openspec new change '<имя>'` — proposal → specs (delta) → design → tasks +2. выполнение задач из `tasks.md` (каждая — с реальной верификацией) +3. `openspec archive '<имя>'` — влить delta в `openspec/specs/`, коммит + +Прямое редактирование файлов или коммиты без openspec-change **запрещены** +(SMTP-фикс 13.09 — прецедент, оформлен постфактум как +`fix-smtp-from-address`). Исключение — только явная команда владельца. + +Подробно: `AGENTS.md` (корень проекта). + ## Команды ```bash diff --git a/openspec/config.yaml b/openspec/config.yaml index 4a38cbc..c94c2ec 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -12,6 +12,7 @@ context: | Мониторинг: Prometheus на bigbox (127.0.0.1:9090, host net), Grafana :3001 (grafana.nixg.ru), Loki :3100 + promtail; метрики GtS: metrics-enabled + OTEL prometheus; логи: log-format json → promtail job. Git: источник истины gitverse.ru (kpa39l), gitea.nixg.ru — pull-mirror (8h). Коммиты — маленькие, по изменениям. Версии: последний стабильный релиз GtS, фиксированный тег в compose, обновление вручную. + СЛУЖЕБНОЕ ПРАВИЛО: ЛЮБОЕ изменение проекта (код, конфиги, доки, статусы) проводится ТОЛЬКО через OpenSpec-воркфлоу (openspec new change → apply tasks → archive): прямое редактирование файлов или коммиты без openspec-change ЗАПРЕЩЕНЫ; исключение — только явная команда пользователя. rules: proposal: diff --git a/openspec/specs/gotosocial/project-governance/spec.md b/openspec/specs/gotosocial/project-governance/spec.md new file mode 100644 index 0000000..75b5772 --- /dev/null +++ b/openspec/specs/gotosocial/project-governance/spec.md @@ -0,0 +1,68 @@ +# gotosocial/project-governance Specification + +## Purpose +Определить обязательный процесс управления изменениями проекта: любое +изменение (код, конфигурация, документация, статусы) проводится только через +OpenSpec-воркфлоу. Введено по явному распоряжению владельца 2026-09-13. + +## Requirements + +### Requirement: OpenSpec-воркфлоу обязателен для всех изменений + +- **MUST**: Каждое изменение проекта оформляется как openspec-change + (`openspec new change ''`) с артефактами proposal → specs (delta) → + design → tasks, в соответствии со schema `spec-driven`. +- **MUST**: Реализация выполняется по задачам из `tasks.md`; каждая задача — + с реальной верификацией (команда/тест/наблюдаемое поведение), подтверждение + «сделано» без проверки не принимается. +- **MUST**: После реализации change архивируется + (`openspec archive '' --yes`), delta вливается в + `openspec/specs//`; итог валиден (`openspec validate`). +- **MUST NOT**: Прямое редактирование файлов проекта (docker-compose.yml, + config.yaml, код, системные юниты, README/STATUS/TODO, openspec/specs) + без openspec-change. + +#### Scenario: Прямая правка запрещена + +- **GIVEN** владелец дал задачу на изменение (например, «добавь правило в файлы») +- **WHEN** агент хочет править файл напрямую, без openspec-change +- **THEN** действие отклоняется: сначала создаётся openspec-change, + задачи применяются, change архивируется + +#### Scenario: Изменение через воркфлоу допустимо + +- **GIVEN** изменение проекта (код или конфиг) +- **WHEN** создан openspec-change, задачи выполнены и верифицированы, + change заархивирован, `openspec validate` проходит +- **THEN** изменение считается легитимным и коммитится + (`feat/fix(...): ...; openspec: `) + +### Requirement: Источники правила для агентов и людей + +- **MUST**: Правило зафиксировано в `AGENTS.md` (корень проекта) — файл + авто-подхватывается агентами (Hermes/Claude) при работе в проекте. +- **MUST**: Правило включено в `openspec/config.yaml` (`context`) — оно + инжектится в каждый артефакт openspec. +- **SHOULD**: Правило продублировано в `README.md` (видно человеку при + первом знакомстве с проектом). + +#### Scenario: Агент видит правило + +- **GIVEN** агент работает в /opt/gotosocial +- **WHEN** он открывает сессию +- **THEN** в `AGENTS.md` он находит «ЖЁСТКОЕ ТРЕБОВАНИЕ: все изменения — + через OpenSpec» с запретами и исключениями + +### Requirement: Исключение только по команде владельца + +- **MAY**: Прямое изменение допускается только после явной команды + владельца («сделай в обход openspec», подтверждение на прямой фикс). +- **MUST**: Исключение фиксируется в коммит-сообщении (например, + `bypass-openspec: <причина>`), чтобы оставаться аудируемым. + +#### Scenario: Явный обход + +- **GIVEN** владелец сказал «сделай напрямую, без openspec» +- **WHEN** агент вносит изменение +- **THEN** изменение допустимо, но помечается в коммите + (`bypass-openspec: <причина>`)