From e4f10dedefde06d5c710ea36ab99b199cf2c1f7f Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Tue, 15 Sep 2026 20:45:41 +0300 Subject: [PATCH] docs: make specs instructions self-contained --- AGENTS.md | 14 +++++++------- AI_INDEX.md | 7 ++++--- README.md | 42 +++++++++++++++++++++++++++++++++++++----- openspec/config.yaml | 6 +++--- 4 files changed, 51 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 54ce275..a8e9696 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,20 +7,20 @@ Если нужна существующая behavioral spec, выбери точный target через [AI_INDEX](AI_INDEX.md). Specs не являются вторым editable HTTP OpenAPI: -backend публикует контракт, а frontend доверяет предоставленному snapshot и -локально проверяет generated types; flow описан в -[docs](../docs/architecture/http-api.md#источник-контракта). +HTTP-провайдер публикует контракт, а потребитель получает отдельный artifact +и локально проверяет generated types. Specs фиксируют behavioral requirements; +другие checkout не нужны для чтения и native validation этого store. Архивы и чужие active changes сохраняй. Для правки индекса проверь targets, anchors и `git diff --check`; application gates принадлежат affected repos. Если явно запрошена работа через OpenSpec, следуй [локальным инструкциям OpenSpec](README.md#начало-работы) -и используй store `wealth-ledger-specs`. Перед Node-командами выбери frontend -`.nvmrc` через `nvm use --silent`, если здесь нет своей. +и используй store `wealth-ledger-specs`. Перед Node-командами активируй +местную `.nvmrc` через `nvm use --silent`. ## Ветки и релизы Работа — в отдельной ветке от `develop`, затем PR в `develop`; в `main` напрямую -не пушить. Release/hotfix и синхронизация веток — по [root README](../README.md#релизы-и-ветки). +не пушить. Release/hotfix и синхронизация веток — по [README](README.md#релизы). Commits и заголовки PR — Conventional Commits; для спецификаций допустим `spec:`. -Перед подготовкой релиза прочитай root README; версии вручную не повышать. +Перед подготовкой релиза прочитай местный README; версии вручную не повышать. diff --git a/AI_INDEX.md b/AI_INDEX.md index a09a10f..cad74ff 100644 --- a/AI_INDEX.md +++ b/AI_INDEX.md @@ -3,13 +3,14 @@ Эти существующие specs — источник сохранённых требований по конкретной теме. Читай нужный requirement/scenario, если задача зависит от него; не загружай всё дерево и не создавай OpenSpec change для обычной разработки. -As-built факты и принятие решений — через [docs index](../docs/README.md). +Этот индекс и основные specs читаются без соседних checkout. Внешние +сведения о реализации служат справочными свидетельствами, когда предоставлены. При конфликте с текущим поведением установи расхождение; не копируй устаревшее правило или случайный код молча. HTTP OpenAPI имеет единственный editable source в backend, а не здесь. -Frontend доверяет предоставленному snapshot и локально проверяет generated -types: [Источник HTTP-контракта](../docs/architecture/http-api.md#источник-контракта). +Потребитель доверяет предоставленному artifact и локально проверяет generated +types. CI каждого участника использует только его собственные входы. | Тема / trigger | Existing spec | | --- | --- | diff --git a/README.md b/README.md index 3d27ef5..cbc971f 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,42 @@ openspec validate --specs --strict --store wealth-ledger-specs Structural validation не заменяет semantic verification и independent read-only review перед archive. +Node задаётся собственной `.nvmrc`; после `nvm use --silent` выполните `npm ci`. +`npm run verify` проверяет diff. OpenSpec validation остаётся отдельной проверкой +при изменениях требований. История релизов — [CHANGELOG](CHANGELOG.md). + ## Релизы -Node задаётся собственной `.nvmrc`; после `nvm use --silent` выполните `npm ci`. -`npm run verify` проверяет diff. Release tooling проверяется из root командой -`node test-release.cjs specs`. OpenSpec validation остаётся отдельной проверкой -при изменениях требований. [Ветки и выпуск](../README.md#релизы-и-ветки), -[история релизов](CHANGELOG.md). +Репозиторий выпускается независимо. `develop` — интеграция, `main` — принятые +релизы. Работа: `codex/` от актуального `develop`, PR в `develop`. +Обычные PR допускают squash; release и обратная синхронизация сохраняют историю. +Commits и PR titles — Conventional Commits, включая `spec:`. Версии вручную не повышай. + +1. Получи `main`, `develop` и теги: `git fetch origin --tags`. Убедись, что + `develop` содержит последний релиз. Создай `release/` от проверенного + `develop`; `nvm use --silent`, `npm ci`. Hotfix начинается от `main` в + `release/hotfix-` и проходит тот же процесс. +2. На чистой ветке выполни `npm run release:preview`, просмотри версию/changelog, + затем `npm run release:prepare`. Команда создаёт `chore(release): X.Y.Z`, + обновляет manifest/lockfile/CHANGELOG; тег и push не выполняет. Не обходи + guards ветки, чистого дерева, отсутствующих тегов или уже подготовленной версии. +3. Проверь diff и штатные gates этого репозитория. Отправь только release-ветку, + открой PR в `main` с заголовком `chore(release): X.Y.Z`. После зелёных + `verify`, `security`, `commits` выполни fast-forward-only merge. Если `main` + изменился, согласуй историю и повтори проверки кандидата. +4. Получи удалённый `main`, сравни его HEAD с проверенным release SHA и версией + manifest/lockfile. Создай аннотированный `vX.Y.Z` именно на этом SHA: + `git tag -a vX.Y.Z -m "Release X.Y.Z"`, затем отправь только + `git push origin refs/tags/vX.Y.Z`. Не запускай release-it повторно на `main`. +5. Верни release-коммит через PR `main → develop` без squash/rebase; проверь, + что `develop` содержит тег. Опубликованные теги не перемещай. При сбое после + merge создай отсутствующий тег без нового bump; до merge исправь и проверь + существующий кандидат без повторного повышения версии. + +`feat:` повышает minor, `fix:`/`perf:` и прочие разрешённые типы — patch; +`!`/`BREAKING CHANGE:` — major, включая версии до 1.0. `chore(release):` +исключён из рекомендации и changelog. Конфигурация — `.release-it.json`. +В Gitea для `main`/`develop` должны быть запрещены прямой/force push и обход +администратором, обязательны `verify`, `security`, `commits`; теги `v*` защищены. +Workflow сам не включает эти настройки. Отдельное review approval для одного +владельца не требуется. Npm publishing, deploy и Gitea Releases не включены. diff --git a/openspec/config.yaml b/openspec/config.yaml index 7f09e44..4bc7bb4 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -2,8 +2,8 @@ schema: wealth-ledger-sdd context: | WealthLedger состоит из независимых frontend, backend, specs и docs Git-репозиториев. - Canonical OpenSpec authority — зарегистрированный store wealth-ledger-specs в specs/openspec. - Docs описывает только фактическое as-built состояние; устойчивые process policies находятся в docs/development. - Локальная разработка и verification выполняются под Node 24 без CI. + Canonical OpenSpec authority — store wealth-ledger-specs в локальном openspec/. + Инструкции и validation specs находятся в этом репозитории; соседние checkout не требуются. + Локальная разработка и CI используют Node из собственной .nvmrc; порядок работы задаёт AGENTS.md. Project artifacts объясняют решения по-русски; exact OpenSpec headings, tokens, commands и normative keywords SHALL/MUST сохраняются на английском. -- 2.54.0