Уточнены правила AGENTS.md по ссылкам, триггерам CI и approval gates

AGENTS.md

@@ -1,91 +1,228 @@
 # AGENTS.md
 
-## General Rules (MUST)
+## Execution Model (MUST)
+- Read this file first; treat as system-level constraints.
+- Priority:
+  1. User instructions
+  2. AGENTS.md
+  3. Existing code/style
+  4. Best practices
+- Prefer minimal, non-breaking changes.
+- Do not introduce unnecessary abstractions.
 
-### Git Collaboration Policy (General)
-- Commit/push only after explicit user approval.
-- After approval: commit and push immediately.
-- Branch switch prompt (`fix/*` or `feat/*`): ask at dialogue start; reuse the explicit user decision for all subsequent fix/feature tasks in the same dialogue.
-- Pending clarification/approval question: ask once, in a single short message; do not repeat the same pending question in a separate final message.
-- After finishing work in `fix/*` or `feat/*`: propose either
-  1. creating an MR into `main`, or
-  2. merging to `main` immediately and deleting the `fix/*`/`feat/*` branch.
-- If push fails: retry up to 2 more times with 3s pause.
-- Approval prompts for pending actions: short direct phrasing, no soft/opening phrases; response format is mandatory:
-  - binary action: yes/no question.
-  - multiple actions/combinations: numbered options only.
+---
 
-### Cleanup (General)
-- Do not leave temporary/debug artifacts in repo.
-- Remove additional debug/temp dirs unless user asked to keep them.
+## Communication (MUST)
+- Answer first, then request approval if needed.
+- Concise, meaningful, no filler.
+- Do not end response with only procedural choice.
 
-### Rules Maintenance (General)
-- For changes to rules files (`AGENTS.md`, `ACTIONS.md`): prefer optimized, compressed edits for AI-agent execution (machine-readable, unambiguous).
-- Keep rule updates minimal and non-duplicative: merge overlapping points, remove redundancy, preserve intent.
+Approval/clarification:
+- ask once, no repetition
+- binary → yes/no
+- multiple → numbered options + brief context
 
-### Communication (General)
-- Project file links in user-facing Markdown: relative paths, `/` separators, spaces encoded as `%20`.
+- File links in repo docs/checklists: relative paths, `/`, spaces as `%20`.
+- In assistant UI responses, use the link format required by the execution environment; include relative path text when possible.
 
-## Project-Specific Rules (MUST)
+---
 
-### Scope
-- Repository purpose: standalone Russian localization mod only.
-- Allowed domain: localization content + packaging/release metadata.
-- Forbidden: gameplay logic, Script Extender content, unrelated assets.
-- Keep repository source-only.
-- Never commit `.pak` or temporary build artifacts.
+## Git Workflow (MUST)
+- Never commit/push without explicit user approval.
+- After approval → commit + push immediately.
+- Commit messages: Russian, factual (what was done).
+- Branch (`fix/*` or `feat/*`): ask once before the first file-changing task that may lead to commit; reuse decision for all subsequent tasks in same dialogue.
 
-### Canonical Paths
-- Mod sources: `Mods/DnD 5.5e AIO Russian`
-- Russian localization: `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
-- Mod metadata: `Mods/DnD 5.5e AIO Russian/meta.lsx`
-- Build script (single source of build truth): `scripts/build.ps1`
-- CI workflow: `.gitea/workflows/build.yml`
-- Glossary (primary terminology reference): `glossary/glossary.normalized.json`
-- Action catalog and command playbooks: `ACTIONS.md`
-- Upstream English reference: `https://github.com/Yoonmoonsik/dnd55e/blob/main/Mods/DnD2024_897914ef-5c96-053c-44af-0be823f895fe/Localization/English/english.xml`
+After work in `fix/*` or `feat/*`:
+1. MR → main
+2. merge → main + delete branch
 
-### Packaging Invariants
-- `.pak` must contain only BG3 mod structure under `Mods/...`.
-- Required content in `.pak`:
-  - `Mods/DnD 5.5e AIO Russian/meta.lsx`
-  - `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
-- Must not leak into `.pak`: `.git`, `.gitea`, `scripts`, `tools`, `.tools`, `build`, staging dirs.
-- Staging for packaging must be in `%TEMP%`, not in dot-prefixed repo dirs.
+Push failure:
+- retry ≤2 times, 3s delay
 
-### Build/CI Contract
-- CI workflow stays thin:
-  1. prepare workspace
-  2. download Divine
-  3. call `scripts/build.ps1`
-  4. publish tag archive
-- Expected build outputs:
-  - `build/DnD 5.5e AIO Russian.pak`
-  - `build/info.json`
-  - `build/DnD 5.5e AIO Russian <tag>.zip` (for tag builds)
-- Release ZIP must include only `.pak` + `info.json`.
-- CI triggers: tag `v*` and manual dispatch; not every push to `main`.
+Release link:
+- provide `[version](url)` immediately after tag push, without waiting for CI
 
-### Version/Release Rules
-- Read release version only from `save/region[@id="Config"]/node[@id="root"]/children/node[@id="ModuleInfo"]/attribute[@id="Version64"]` via explicit XML parsing.
-- `PublishVersion` must not be changed during release preparation.
-- Release tag must match the source-of-truth version.
-- Decision logic before tagging:
-  1. If `ModuleInfo/Version64` was manually changed (e.g. BG3 Toolkit), use matching tag and release.
-  2. If `ModuleInfo/Version64` equals latest released version, bump version first (e.g. `scripts/set-version.ps1 -VersionTag <tag>`), commit, then create/push tag.
-- `scripts/build.ps1` derives release `Version64` from tag and writes it to generated `info.json` and staged `meta.lsx`.
+---
 
-### info.json Contract
-- Top-level keys: `Mods`, `MD5`.
-- Per-mod keys: `Author`, `Name`, `Folder`, `Version`, `Description`, `UUID`, `Created`, `Dependencies`, `Group`.
-- `Dependencies` is an array of UUIDs.
-- Current dependency UUID: `897914ef-5c96-053c-44af-0be823f895fe`.
+## Scope (MUST)
+- Repo = Russian localization mod only.
 
-### Git Collaboration Policy (Project-Specific)
-- Commit messages and comments: Russian.
-- Commit message content: what was done (not what should be done).
-- If changes affect `.pak` contents or build/release flow: propose releasing next version.
-- For released versions in user-facing messages: provide direct archive link in Markdown format `[version](url)` when derivable (acceptable immediately after tag push, even before CI finishes).
+Allowed:
+- localization content
+- packaging/release metadata
 
-### Cleanup (Project-Specific)
-- Ignored/temp patterns include: `build/`, `build-stage*`, `.tools/`, `*.pak`.
+Forbidden:
+- gameplay logic
+- Script Extender
+- unrelated assets
+
+- Repo must remain source-only.
+- Never commit `.pak` or build artifacts.
+
+---
+
+## Paths (MUST)
+- Mod: `Mods/DnD 5.5e AIO Russian`
+- Localization: `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
+- Metadata: `Mods/DnD 5.5e AIO Russian/meta.lsx`
+- Build: `scripts/build.ps1` _(single source of build truth)_
+- CI: `.gitea/workflows/build.yml`
+- Glossary: `glossary/glossary.normalized.json` _(primary terminology reference)_
+- Actions: `ACTIONS.md`
+- Upstream EN reference: `https://github.com/Yoonmoonsik/dnd55e/blob/main/Mods/DnD2024_897914ef-5c96-053c-44af-0be823f895fe/Localization/English/english.xml`
+
+---
+
+## Packaging (MUST)
+- `.pak` contains ONLY `Mods/...`
+
+Required:
+- `meta.lsx`
+- `russian.xml`
+
+Forbidden in `.pak`:
+- `.git`, `.gitea`
+- `scripts`, `tools`, `.tools`
+- `build`, staging dirs
+
+Staging:
+- use `%TEMP%`
+- not inside repo
+
+---
+
+## Build & CI (MUST)
+Flow:
+1. prepare
+2. download Divine
+3. run `scripts/build.ps1`
+4. publish
+
+Outputs:
+- `build/*.pak`
+- `build/info.json`
+- `build/*.zip` (tag only)
+
+Release ZIP:
+- only `.pak` + `info.json`
+
+Triggers:
+- automatic: push tag `v*`
+- manual: workflow_dispatch
+- branch pushes without tag MUST NOT publish release artifacts
+
+---
+
+## Versioning (CRITICAL)
+Source of truth:
+`ModuleInfo/Version64` — read via explicit XML parsing:
+`save/region[@id="Config"]/node[@id="root"]/children/node[@id="ModuleInfo"]/attribute[@id="Version64"]`
+
+Rules:
+- do not change `PublishVersion`
+- tag MUST match version
+
+Before tag:
+1. if version already changed → use it
+2. if same as last → bump:
+   `scripts/set-version.ps1 -VersionTag <tag>`
+
+`build.ps1`:
+- derives version from tag
+- writes to `info.json` + staged `meta.lsx`
+
+Conflict resolution (MUST):
+- before release, `Version64` in `meta.lsx` MUST equal target tag version
+- if mismatch, run `scripts/set-version.ps1 -VersionTag <tag>` and re-check
+- if still mismatch, release is blocked
+
+---
+
+## info.json (MUST)
+Root:
+- `Mods`, `MD5`
+
+Per mod:
+- Author, Name, Folder, Version
+- Description, UUID, Created
+- Dependencies (array), Group
+
+Dependency UUID:
+`897914ef-5c96-053c-44af-0be823f895fe`
+
+---
+
+## Guardrails (MUST)
+
+Before commit:
+- scope valid (localization/metadata only)
+- no forbidden content
+- no build artifacts (`.pak`, `build/`, staging)
+- no temp/debug artifacts; ignored patterns MUST be present in `.gitignore`: `build/`, `build-stage*`, `.tools/`, `*.pak`
+- packaging invariants intact
+- version consistent (if applicable)
+
+Before push:
+- explicit user approval
+- commit message valid (RU, factual)
+
+Before release:
+- version == tag
+- version bumped if needed
+- CI/build contract valid
+- outputs correct (no extra files)
+
+---
+
+## Release & Changelog (MUST)
+
+- Every release MUST include changelog.
+
+Changelog:
+- language: Russian
+- concise, user-facing
+- describe WHAT changed
+- group logically
+
+Sources:
+- prefer diff over commits
+
+Diff rules:
+- inspect real file changes
+
+Localization (`russian.xml`):
+- added / changed / removed strings
+- summarize user-visible impact (UI, spells, descriptions)
+
+Metadata / CI:
+- describe effect, not raw edits
+
+Large diff:
+- group + summarize
+
+If no visible changes:
+- state "техническое обновление"
+
+Before release:
+- generate changelog draft
+- ask for approval
+
+Approval gates:
+- Gate A: explicit approval for commit/push (code/content changes)
+- Gate B: explicit approval for release publish (after changelog draft)
+
+Release message:
+- version
+- changelog
+- `[version](url)` if derivable
+
+Do not:
+- invent changes
+- include internal noise
+
+---
+
+## Rules Maintenance (MUST)
+- Changes to `AGENTS.md` / `ACTIONS.md`: prefer compressed, machine-readable edits.
+- Keep updates minimal and non-duplicative: merge overlapping points, remove redundancy, preserve intent.