nitra · vitaliytv · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/.changes/260809-1605.md b/.changes/260809-1605.md
@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Added
+---
+docs(architecture): principles.md — зведення 26 принципів канону і три шари обовʼязковості (normativity: principle/contract/reference) у фронтматері кожної глави
diff --git a/.cspell.json b/.cspell.json
@@ -59,6 +59,7 @@
     "NAPI",
     "NCURSOR",
     "nitralabs",
+    "normativity",
     "nowarn",
     "ollama",
     "Ollama",

diff --git a/docs/architecture/access.md b/docs/architecture/access.md
@@ -1,5 +1,6 @@
 ---
 type: architecture
+normativity: contract
 description: 'Акаунти і ключі пристроїв, relay та membership, ролі, три approval-гейти з Ed25519-підписами, push'
 tags: [access, relay, membership, approvals, security]
 timestamp: 2026-07-07

diff --git a/docs/architecture/git.md b/docs/architecture/git.md
@@ -1,5 +1,6 @@
 ---
 type: architecture
+normativity: contract
 description: 'CAS claim як єдине «перо», run ref із журналом сесії, fenced publish і паралельне виконання'
 tags: [git, claim, lease, publish]
 timestamp: 2026-07-07
@@ -69,6 +70,8 @@ Run ref: `refs/mt/runs/<node-hash>/<token>` — гілка робочого ст
 
 **Wrapper** (`mt run`; у цільовій картині — роль Runner всередині agent-server): перевіряє deps resolved + відсутність pending-audit → CAS claim → detached worktree від `base_sha` → run ref → запускає агента → watchdog → пише `run_NNN.md` → publish.
 
+> **Реалізація (не контракт).** Імена ENV нижче — інтерфейс усередині однієї реалізації (wrapper → агент), а не межа між реалізаціями: інша реалізація може назвати їх інакше, не порушивши сумісності git-стану. Нормативна тут лише семантика `generation` як fencing token.
+
 **ENV-контракт wrapper → агент:** `MT_BUDGET_SEC`, `MT_HARD_BUDGET_SEC`, `MT_STARTED_AT`, `MT_RUN_NNN`, `MT_ATTEMPT`, `MT_CLAIM_TOKEN`, `MT_CLAIM_GENERATION`. `MT_CLAIM_GENERATION` — fencing token для non-idempotent side effects: single publish owner гарантує лише один запис результату в `main`, не mutual exclusion виконання.
 
 ## Fenced publish

diff --git a/docs/architecture/graph.md b/docs/architecture/graph.md
@@ -1,5 +1,6 @@
 ---
 type: architecture
+normativity: contract
 description: 'Вузли й ОАГ, файловий контракт, derived-стани, два етапи виконання, retry ladder і аудит'
 tags: [graph, contract, states, audit]
 timestamp: 2026-07-07
@@ -131,7 +132,7 @@ parent: research/collect-data # відносно mt/; відсутній у ко
 ---
 schema_version: 1
 created_at: ISO8601
-model_tier: AVG        # MIN | AVG | MAX; default AVG
+model_tier: AVG        # MIN | AVG | MAX; дефолт — довідник operations.md
 agent_cli: codex       # опціонально; claude | codex | cursor | pi — підписочний CLI (runtime.md)
 skills: [bash, write-files]
 secrets: [STRIPE_KEY]  # опціонально; wrapper інжектить через ENV
@@ -142,7 +143,7 @@ interactive: false     # НОВЕ: true → вузол очікує інтера
 ---
 ```
 
-`model_tier` — джерело істини виконавця. Runner резолвить tier у **конкретну модель обраного CLI** через user-level env `MT_AGENT_CLI_MODEL_MAP[<cli>][tier]` (напр. codex: MIN→luna / AVG→terra / MAX→sola); CLI без мапінгу резолвить модель сам за підпискою користувача, tier завжди передається hint-ом env `MT_MODEL_TIER` ([runtime.md](runtime.md#підписочні-cli-виконавці-agent_cli)).
+`model_tier` — джерело істини виконавця. Runner резолвить tier у **конкретну модель обраного CLI** через user-level env `MT_AGENT_CLI_MODEL_MAP[<cli>][tier]` ([operations.md](operations.md#конфігурація-mtjson)); CLI без мапінгу резолвить модель сам за підпискою користувача, tier завжди передається hint-ом env `MT_MODEL_TIER` ([runtime.md](runtime.md#підписочні-cli-виконавці-agent_cli)).
 
 `agent_cli` (який підписочний CLI виконує вузол) — **per-node** прапор `a.md` з user-level дефолтом env `MT_AGENT_CLI`. Per-node вибір CLI — це крос-програмковий вимір [мети](../vision.md): спеціалізований тул на вузол.
 
@@ -331,7 +332,9 @@ context = [task.md] + [a.md|h.md] + [deps/] + [plan_*.md] +
 
 ## Retry ladder, engineer, unresolvable
 
-До `agent_retry_max` (3) вузол лишається `waiting`; агент ретраїть за драбиною (`MT_ATTEMPT` = failed_streak + 1): 1 — базова; 2 — diagnose-first; 3 — alternative-approach (`model_tier: +1`, `skills_add`). Коротша драбина → останній щабель повторюється.
+> **Реалізація (не контракт).** Контрактні тут — механізм драбини, лічильник `failed_streak` і три умови `unresolvable`. Значення `agent_retry_max` і склад щаблів `retry_ladder` — референсні: реалізація може мати інші, лишаючись сумісною. Дефолти — [довідник](operations.md#дефолти-на-які-посилаються-глави).
+
+До `agent_retry_max` вузол лишається `waiting`; агент ретраїть за драбиною `retry_ladder` (`MT_ATTEMPT` = failed_streak + 1). Щабель може змінювати стратегію промпта, `model_tier` і `skills_add`; коротша драбина → останній щабель повторюється.
 
 **EngineerAgent:** `failed_streak ≥ agent_retry_max` → `mt run --actor engineer`: отримує task + deps + повний run-history + `.mt/engineer-prompt.md`; може `mt stop`/`invalidate`/`kill`/GraphPatch.
 

diff --git a/docs/architecture/i18n.md b/docs/architecture/i18n.md
@@ -1,5 +1,6 @@
 ---
 type: architecture
+normativity: contract
 description: 'Багатомовність: base-канон і derived-переклади у refs/mt/i18n, worktree-матеріалізація, contract-aware перекладач, authored-захист'
 tags: [i18n, translations, languages, worktree]
 timestamp: 2026-07-07
@@ -111,6 +112,8 @@ claim → worktree від base_sha
 
 ## Конфігурація
 
+> **Реалізація (не контракт).** Імена ключів і дефолтні значення — референсні; контрактне — існування base-мови, `source_hash` у схемі перекладу і триступенева схема «що перекладається».
+
 ```jsonc
 // .mt.json
 {

diff --git a/docs/architecture/index.md b/docs/architecture/index.md
@@ -4,6 +4,7 @@
 
 ## Глави (за порядком читання)
 
+* [Принципи і шари обовʼязковості](principles.md) - зведення інваріантів канону і критерій `principle` / `contract` / `reference`
 * [Огляд: рішення злиття і шари системи](overview.md) - шість нормативних рішень обʼєднання і чотиришарова діаграма
 * [Ядро: рекурсивний граф задач](graph.md) - вузли й ОАГ, файловий контракт, derived-стани, два етапи виконання, retry ladder, аудит
 * [Координація через git](git.md) - CAS claim (create/renewal/takeover/handoff), run ref і журнал сесії, fenced publish, паралелізм
@@ -20,3 +21,5 @@
 
 * [Референсний стек](stack.md) - конкретні технологічні рішення реалізації; зміна стеку не змінює архітектуру
 * [Журнал змін](../log.md) - хронологія редакцій
+
+Кожна глава несе у фронтматері поле `normativity` — шар обовʼязковості її змісту; секції, що відхиляються від рівня своєї глави, позначені блок-цитатою «Реалізація (не контракт)». Значення шарів і критерій віднесення — [principles.md](principles.md).
diff --git a/docs/architecture/mandates.md b/docs/architecture/mandates.md
@@ -1,5 +1,6 @@
 ---
 type: architecture
+normativity: contract
 description: 'Карта мандатів, профілі людей і моделей, decision-request, ескалація за важелем, прецедентний рушій — людина як власник рішень свого горизонту, не exception-handler'
 tags: [mandates, escalation, decision-request, competencies, human-in-the-loop]
 timestamp: 2026-07-12

diff --git a/docs/architecture/operations.md b/docs/architecture/operations.md
@@ -1,5 +1,6 @@
 ---
 type: architecture
+normativity: contract
 description: 'CLI-контракт, конфігурація, монорепо, security model, відмовостійкість, bootstrap і наскрізні сценарії'
 tags: [operations, cli, config, security, scenarios]
 timestamp: 2026-07-07
@@ -46,6 +47,8 @@ mt template run <name>            ← позачергова матеріалі
 
 ## Конфігурація (`.mt.json`)
 
+> **Реалізація (не контракт).** Нормативні тут — межа «repo-scoped `.mt.json` vs user-level ENV», порядок пріоритету і `schema_version` як fail-closed-гейт. Імена ключів, їх дефолтні значення і довідник нижче — референсні.
+
 До конфігурації 0.2.0 (claim/publish/budget/retry/audit/model/skill_profiles — без змін) додаються:
 
 ```json
@@ -63,7 +66,14 @@ mt template run <name>            ← позачергова матеріалі
 }
 ```
 
-Конфігурація **виконавців** (провайдери/моделі) — не тут: вона user-level, спільна для всіх репозиторіїв, і живе в ENV (`MT_AGENT_CLI`, `MT_CLOUD_AGENT_CLIS`, `MT_AGENT_CLI_MODEL_MAP` — [runtime.md](runtime.md#підписочні-cli-виконавці-agent_cli)). `.mt.json` — виключно repo-scoped.
+Конфігурація **виконавців** (провайдери/моделі) — не тут: вона user-level, спільна для всіх репозиторіїв, і живе в ENV. Семантику цих змінних задає [runtime.md](runtime.md#підписочні-cli-виконавці-agent_cli); значення — тут. `.mt.json` — виключно repo-scoped.
+
+```bash
+# ~/.zshenv (рівень користувача — усі репозиторії)
+export MT_AGENT_CLI="claude"                       # дефолтний виконавець
+export MT_CLOUD_AGENT_CLIS="codex,cursor"          # каскад хмарних підписок (порядок = пріоритет)
+export MT_AGENT_CLI_MODEL_MAP='{"codex":{"MIN":"gpt-5.6-luna","AVG":"gpt-5.6-terra","MAX":"gpt-5.6-sola"},"pi":{"MIN":"omlx/gemma-4-e2b-it-4bit"}}'
+```
 
 **Модель виконавця:** канон тирів MIN/AVG/MAX резолвиться у конкретну модель обраного CLI через env `MT_AGENT_CLI_MODEL_MAP` ([runtime.md](runtime.md#підписочні-cli-виконавці-agent_cli)). Автономні run-и обирають за `model_tier` з `a.md`; інтерактивні можуть перевизначати CLI per-turn за `surface`-hint (`surface_profiles`). Транспорт AI-викликів — виключно **ACP** (конкретика — у [stack.md](stack.md)).
 
@@ -89,6 +99,18 @@ Baseline-ключі 0.2.0 з конкретними дефолт-значенн
 | Relay/хост | `relay_url`, `server_port_file` | тут, [runtime.md](runtime.md) |
 | i18n | `i18n.{base_lang, eager, publish_langs, include, exclude, model_tier, ttl_days}` | [i18n.md](i18n.md) |
 
+### Дефолти, на які посилаються глави
+
+Глави описують **семантику** ключа й посилаються на його ім'я; конкретне значення живе тут. Канонічне джерело baseline-дефолтів — `CONFIG_DEFAULTS` у коді (вище); таблиця нижче — довідкове дзеркало для читача спеки, і як усе в шарі `reference` розбіжність із нею не є порушенням контракту.
+
+| Ключ / параметр | Дефолт | Семантику описує |
+| --- | --- | --- |
+| `model_tier` (`a.md`) | `AVG` | [graph.md](graph.md) |
+| `agent_cli` (`a.md`) / `MT_AGENT_CLI` | `claude` | [runtime.md](runtime.md#підписочні-cli-виконавці-agent_cli) |
+| `agent_retry_max` | `3` | [graph.md](graph.md) |
+| `retry_ladder` | три щаблі: базова спроба → `diagnose-first` → `alternative-approach` (`model_tier: +1`, `skills_add`) | [graph.md](graph.md) |
+| Ліміт кадру протоколу подій | 2 MB (спільний з relay) | [runtime.md](runtime.md), [access.md](access.md) |
+
 ## Монорепо: множинні `mt/`
 
 ```