Уточнены правила 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.

Mods/DnD 5.5e AIO Russian/meta.lsx

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <save>
     <version major="4" minor="8" revision="0" build="500"/>
     <region id="Config">
@@ -9,11 +9,11 @@
                     <children>
                         <node id="ModuleShortDesc">
                             <attribute id="Folder" type="LSString" value="DnD2024_897914ef-5c96-053c-44af-0be823f895fe"/>
-                            <attribute id="MD5" type="LSString" value="ac497558b070a635abecd7d23d4a3125"/>
+                            <attribute id="MD5" type="LSString" value="4bd42ca93f895d1ec521a286bea09ef2"/>
                             <attribute id="Name" type="LSString" value="DnD 5.5e All-in-One BEYOND"/>
                             <attribute id="PublishHandle" type="uint64" value="4419649"/>
                             <attribute id="UUID" type="guid" value="897914ef-5c96-053c-44af-0be823f895fe"/>
-                            <attribute id="Version64" type="int64" value="144396678084952064"/>
+                            <attribute id="Version64" type="int64" value="144396675937468416"/>
                         </node>
                     </children>
                 </node>
@@ -32,7 +32,7 @@
                     <attribute id="PublishHandle" type="uint64" value="5965149"/>
                     <attribute id="StartupLevelName" type="FixedString" value=""/>
                     <attribute id="UUID" type="FixedString" value="6401e84d-daf2-416d-adeb-99c03a2487a6"/>
-                    <attribute id="Version64" type="int64" value="281483566645248"/>
+                    <attribute id="Version64" type="int64" value="281485714128896"/>
                     <children>
                         <node id="PublishVersion">
                             <attribute id="Version64" type="int64" value="281477124194304"/>

scripts/build.ps1

@@ -101,10 +101,10 @@ if (-not (Test-Path -LiteralPath $stagedMetaPath)) {
     throw "Staged meta.lsx was not found: '$stagedMetaPath'."
 }
 
-$stagedMetaContent = Get-Content -LiteralPath $stagedMetaPath -Raw
+$utf8Encoding = [System.Text.UTF8Encoding]::new($false)
+$stagedMetaContent = [System.IO.File]::ReadAllText($stagedMetaPath, $utf8Encoding)
 $stagedMetaContent = $stagedMetaContent -replace '(<attribute id="Version64" type="int64" value=")\d+("/>)', "`${1}$resolvedVersion64`${2}"
-$utf8Bom = New-Object System.Text.UTF8Encoding($true)
-[System.IO.File]::WriteAllText($stagedMetaPath, $stagedMetaContent, $utf8Bom)
+[System.IO.File]::WriteAllText($stagedMetaPath, $stagedMetaContent, $utf8Encoding)
 
 Write-Host "[build.ps1] Staged source tree:"
 Get-ChildItem -Recurse $stagingPath | Select-Object FullName, Length | Format-Table -AutoSize

scripts/set-version.ps1

@@ -35,7 +35,8 @@ if (-not (Test-Path -LiteralPath $resolvedMetaPath)) {
 }
 
 $resolvedVersion64 = Convert-VersionTagToVersion64 -Tag $VersionTag
-$metaContent = Get-Content -LiteralPath $resolvedMetaPath -Raw
+$utf8Encoding = [System.Text.UTF8Encoding]::new($false)
+$metaContent = [System.IO.File]::ReadAllText($resolvedMetaPath, $utf8Encoding)
 [xml]$metaXml = $metaContent
 
 # Explicitly target ModuleInfo/Version64 via XML path to avoid touching Dependencies/PublishVersion.
@@ -57,7 +58,6 @@ $updatedMeta = [regex]::Replace(
     1
 )
 
-$utf8Bom = New-Object System.Text.UTF8Encoding($true)
-[System.IO.File]::WriteAllText($resolvedMetaPath, $updatedMeta, $utf8Bom)
+[System.IO.File]::WriteAllText($resolvedMetaPath, $updatedMeta, $utf8Encoding)
 
 Write-Host "[set-version.ps1] Updated '$resolvedMetaPath' to Version64=$resolvedVersion64 (from tag '$VersionTag')."