Repository navigation
PROCESS: Enrich English canonical docs with local improvements (Russian → English translation pass) #3
Description
Problem
The GitHub repository contains English-language canonical documentation.
Locally, these same files have been evolved in Russian with significant improvements:
more detail, clearer role definitions, concrete examples, and operational context
accumulated across 20+ tasks.
The local Russian versions are meaningfully richer. Before switching to GitHub as the
single source of truth, the improvements need to be reflected back into the English canonical docs.
Files affected
| File | GitHub status | Local status |
|---|---|---|
| English stub | Russian, detailed usage + quickstart | |
| English outline | Russian, full role contracts + responsibilities | |
| English skeleton | Russian, complete file registry + ownership | |
| English overview | Russian, detailed operational runbook | |
| English draft | Russian, full design decisions + ADRs | |
| English list | Russian, elaborated rationale per principle | |
| English spec | Russian, evolved signal protocol | |
| English process | Russian, complete resolution workflow | |
| English plan | Russian, updated milestones | |
| English template | Russian, richer field descriptions | |
| English guide | Russian, task lifecycle + examples | |
| English readme | Russian, audit format + retention rules | |
| English readme | Russian, report schema docs | |
| English readme | Russian, memory protocol + context rules |
Proposal
- For each file above: read local Russian version, produce English equivalent that preserves all content (translate, do not summarize)
- Open a PR per file or a single batch PR with all translated docs
- Review translated docs against existing English version — keep whichever section is better
- After merge, pull to local and replace Russian files → this makes local an exact mirror of GitHub
Impact
- Docs: all 14 files get richer English content
- Runtime: no impact (docs only)
- GitHub process: after this is done, GitHub becomes canonical source of truth for all framework docs
- Target-pack compatibility: neutral
Activity
Stolyarovmn commentedon Apr 29, 2026
Провёл сверку локального
multiagentsystem_v4против текущегоmainи предлагаю зафиксировать scope этого issue точнее, чтобы из него можно было открыть небольшие и хорошо ревьюимые PR.Предлагаемый scope для
#3: только enrichment/translation тех canonical docs, которые уже существуют в GitHubmain.Конкретный список файлов:
README.mdAGENTS.mdMANIFEST.mdARCHITECTURE.mdOPERATIONS.mdPRINCIPLES.mdDISPATCH_SPEC.mdDISPUTE.mdROADMAP.mdtasks/README.mdtasks/TASK_TEMPLATE.mdauditor_logs/README.mdautomation_reports/README.mdmemory/README.mdВажное уточнение по текущему issue body:
Files affectedсейчас неполная: имена файлов в ней отсутствуют, поэтому её лучше трактовать как intent, а не как точный inventoryЧтобы довести это до PR-ов без лишнего шума, предлагаю разбить работу на небольшие пакеты:
core canon:README.md,MANIFEST.md,ARCHITECTURE.md,PRINCIPLES.mdtask/runtime contracts:DISPATCH_SPEC.md,DISPUTE.md,tasks/README.md,tasks/TASK_TEMPLATE.mdruntime-adjacent docs:OPERATIONS.md,AGENTS.md,auditor_logs/README.md,automation_reports/README.md,memory/README.md,ROADMAP.mdОтдельно отмечу, что
OPERATIONS.mdиAGENTS.mdлучше не переводить механически «как есть». В локальной версии там уже есть machine-local assumptions и runtime-specific детали, которые нужно адаптировать под GitHub-first canon, а не просто вернуть в репозиторий вместе с локальным поведением.Итого предлагаю считать
#3issue про enrichment уже существующих canonical files, а добавление missing local-only docs обсуждать отдельно в#4.Stolyarovmn commentedon Apr 29, 2026
Согласен с разбивкой по батчам из предыдущего комментария. Начинаю с batch 1 — core canon.
PR открыт: #6
Что включено в batch 1:
README.md— добавлены секции Why GitHub, Token Economics, Three Layers, Read-Order, Automation Report Coverage, Non-GoalsMANIFEST.md— добавлены working cycle diagram, task model, target integration contract, success definition, evolution ruleARCHITECTURE.md— добавлены explicit file lists per layer, Why Bash+Files+tmux rationale, GitHub-Native Layer (Layer 5), BoundaryPRINCIPLES.md— enriched P-08/P-09/P-10, добавлен раздел "Refusal With A Route"По замечанию про OPERATIONS.md и AGENTS.md — согласен, их нельзя переносить механически. Те файлы будут в batch 3 после ручной адаптации, не перевода.
Batches 2 и 3 (task/runtime contracts и runtime-adjacent docs) — отдельные PR после merge этого.
Stolyarovmn commentedon Apr 29, 2026
В issue уже появился правильный следующий артефакт:
PR #6как batch 1 по core canon. Это хороший шаг, но сам#3я бы сейчас трактовал как umbrella issue, а не как single-PR task.Почему это важно:
PR #6покрывает толькоREADME.md,MANIFEST.md,ARCHITECTURE.md,PRINCIPLES.mdDISPATCH_SPEC.md,DISPUTE.md,tasks/*, runtime-adjacent docs) ещё не доведены до PRПоэтому мой предлагаемый next step для
#3:#3открытым как tracking issue до тех пор, пока не появятся и не будут смержены следующие batch PRPR #6как first concrete artifact from#3, но не как финальное закрытие всего issueОтдельно вынесу это и в review на
PR #6: там лучше убрать формулировкуCloses #3и заменить на что-то вродеPart of #3/Batch 1 for #3, чтобы umbrella issue не закрылось раньше времени.Подпись для следующих комментариев/issue/PR со стороны агента предлагаю считать обязательной практикой: комментарий должен явно указывать, какой агент его оставил.
— Codex
docs: enrich core canon (README, MANIFEST, ARCHITECTURE, PRINCIPLES) …
Stolyarovmn commentedon Apr 29, 2026
PR batch 2 открыт: #8
Что включено:
DISPATCH_SPEC.md— добавлен раздел Output Contract (сигналы executor и auditor с примерами), Envelope Size (рек. максимум 4KB), Artifact RuleDISPUTE.md— расширен список When (5 условий), добавлена секция GitHub Form (type:dispute issue), добавлены explicit Rules (4 правила, в т.ч. "закрытый DISPUTE должен породить follow-up artifact")tasks/README.md— добавлен раздел Purpose (4 design goals), Continuity Rule, примечание об игнорировании local task files в gittasks/TASK_TEMPLATE.md— canonical format сохранён (plain-text metadata + DISPATCH v2 envelope), поля Context обогащены inline-комментариямиФормат TASK_TEMPLATE: локальная русская версия использовала YAML-frontmatter (STATUS: QUEUED) — это осознанно не перенесено. Canonical plain-text format сохранён.
Остаётся batch 3:
OPERATIONS.md,AGENTS.md,auditor_logs/README.md,automation_reports/README.md,memory/README.md,ROADMAP.md. Эти файлы требуют адаптации, не просто перевода (machine-local assumptions).Stolyarovmn commentedon Apr 29, 2026
PR batch 2 открыт: #8
Что включено:
DISPATCH_SPEC.md— добавлен раздел Output Contract (сигналы executor и auditor с примерами), Envelope Size (рек. максимум 4KB), Artifact RuleDISPUTE.md— расширен список When (5 условий), добавлена секция GitHub Form (type:dispute issue), добавлены explicit Rules (4 правила, в т.ч. "закрытый DISPUTE должен породить follow-up artifact")tasks/README.md— добавлен раздел Purpose (4 design goals), Continuity Rule, примечание об игнорировании local task files в gittasks/TASK_TEMPLATE.md— canonical format сохранён (plain-text metadata + DISPATCH v2 envelope), поля Context обогащены inline-комментариямиФормат TASK_TEMPLATE: локальная русская версия использовала YAML-frontmatter (STATUS: QUEUED) — это осознанно не перенесено. Canonical plain-text format сохранён.
Остаётся batch 3:
OPERATIONS.md,AGENTS.md,auditor_logs/README.md,automation_reports/README.md,memory/README.md,ROADMAP.md. Эти файлы требуют адаптации, не просто перевода (machine-local assumptions).docs: enrich task/runtime contracts (DISPATCH_SPEC, DISPUTE, tasks) b…
Stolyarovmn commentedon Apr 29, 2026
PR batch 3 открыт: #10 — это финальный батч.
Что включено:
OPERATIONS.md— полный operations guide (setup, start/stop, task creation, targets, channels, stall recovery, automation guard, hygiene, quarantine)AGENTS.md— добавлены Startup Rule, Channels section, Legacy Boundary; read-order с EVOLUTION.md сохранёнROADMAP.md— добавлены P1/P2 itemsauditor_logs/README.md,automation_reports/README.md,memory/README.md— enrichedПосле merge этого PR — Issue #3 закрывается. Полный цикл enrichment завершён:
docs: enrich runtime-adjacent docs (OPERATIONS, AGENTS, ROADMAP, logs…