From 2c2a39419c6d4ebed6e61fa7ae1f0c915b71e25a Mon Sep 17 00:00:00 2001
From: vitaliytv <v@nitra.ai>
Date: Sun, 9 Aug 2026 15:27:55 +0300
Subject: [PATCH] =?UTF-8?q?docs(graph):=20a.md/h.md=20=E2=80=94=20YAML-?=
 =?UTF-8?q?=D1=84=D1=80=D0=BE=D0=BD=D1=82=D0=BC=D0=B0=D1=82=D0=B5=D1=80=20?=
 =?UTF-8?q?=D1=83=20markdown,=20=D0=BD=D0=B5=20=D0=B3=D0=BE=D0=BB=D0=B8?=
 =?UTF-8?q?=D0=B9=20YAML?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Спека показувала прапори виконавця у fence ```yaml без `---`, тобто
як голий YAML у файлі з розширенням .md — на відміну від task.md,
plan_NNN.md, run_NNN.md, які подані як ```markdown із фронтматером.
Це була неточність подання, а не свідоме рішення: контракт голого
YAML належить .yml-файлам (.mt-claim.yml).

Тепер a.md/h.md явно задані як фронтматер + вільне тіло: узгоджено з
рештою .md-артефактів, один код-шлях парсингу, нормальний рендер при
рев'ю і місце для прози (для h.md — розгорнутий опис кваліфікації).

Реалізація: nitra/mt-rust (жорсткий перехід, dogfood-граф мігровано).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .cspell.json               |  1 +
 docs/architecture/graph.md | 12 ++++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.cspell.json b/.cspell.json
index 7378dca..4d85147 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -536,6 +536,7 @@
     "фолбеком",
     "форвардить",
     "фронтенд",
+    "фронтматер",
     "фронтматері",
     "фронтматером",
     "фронтматеру",
diff --git a/docs/architecture/graph.md b/docs/architecture/graph.md
index 75b2f13..a043640 100644
--- a/docs/architecture/graph.md
+++ b/docs/architecture/graph.md
@@ -125,7 +125,10 @@ parent: research/collect-data # відносно mt/; відсутній у ко
 
 #### `a.md`
 
-```yaml
+Як і решта `.md`-артефактів вузла — YAML-фронтматер у markdown-файлі: дані в `---`-блоці, тіло вільне (нотатка людини, чому саме такий виконавець). Голий YAML без `---` — контракт `.yml`-файлів (`.mt-claim.yml`), не `.md`.
+
+```markdown
+---
 schema_version: 1
 created_at: ISO8601
 model_tier: AVG        # MIN | AVG | MAX; default AVG
@@ -136,6 +139,7 @@ retry_ladder:          # опціонально; per-node override
   - {}
   - strategy: diagnose-first
 interactive: false     # НОВЕ: true → вузол очікує інтерактивну сесію (див. runtime.md)
+---
 ```
 
 `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)).
@@ -144,12 +148,16 @@ interactive: false     # НОВЕ: true → вузол очікує інтера
 
 #### `h.md`
 
-```yaml
+Той самий контракт, що й `a.md`: фронтматер + вільне тіло (розгорнутий опис кваліфікації прозою).
+
+```markdown
+---
 schema_version: 1
 created_at: ISO8601
 assignee: vkozlov          # handle; мапінг на account_id relay — .mt/directory.json (git-ignored)
 notify: true               # relay шле push на пристрої assignee
 qualification: 'senior backend engineer'
+---
 ```
 
 #### `plan_NNN.md`