---
name: koi-project-onboard
description: >-
  Attach an existing code repository to ResearchOS via a persistent Socratic
  interview with semantic quality gates (problem → program → cause/hyp →
  method), then a cold-reader clarity loop on titles only (≤6 iterations;
  descriptions out of scope), koi-prose-style, write
  tree/REPO/koi-structure/project.md, then install_cli (orphan koi/research +
  tree worktree). TRIGGER when the user asks to «подключить проект», onboard,
  attach a repo to ResearchOS, or points at a sibling folder with code but no
  koi-structure/.
---

# KOI: онбординг проекта (attach)

Подключить репозиторий **с уже существующим кодом** к ResearchOS и построить
**скелет** дерева: problem → cause → remediation|cause_evidence → method.

Это **attach** по ADR-001. Канонический путь материалов:

```text
tree/<repo>/koi-structure/project.md   # ветка koi/research (worktree)
<repo>/                                # код, любая ветка
```

Не создание пустого проекта из UI и не полный Related Work. Пустой проект без
кода — `python -m koi.projects.install_cli install <name> --create`.

Type-checks формулировок и шаблон frames — в
[framing-checks.md](framing-checks.md).

**Бриф-якорь (обязательно на диске):** по мере диалога веди и в конце запиши
`tree/<repo>/koi-structure/onboard-brief.md` (legacy: `<repo>/koi-structure/…`)
по шаблону [onboard-brief.template.md](onboard-brief.template.md). Это
зафиксированные высокие цели/problem/cause/hyp/method из слоёв 3A–3C. Перед
**любым** написанием или правкой заголовков узлов/карточек (фиксация слоя,
clarity loop, prose-pass, поздние правки дерева) — **перечитай
`onboard-brief.md`** и сверяй titles с ним. Cold reader файл не получает.

**Стиль текста (обязательно, на каждое сообщение):** любое обращение к
человеку в онбординге — бриф, сверка с литературой, комментарий, вопрос,
фиксация узла, резюме skeleton — пишется по правилам
[`koi-prose-style`](../koi-prose-style/SKILL.md) (естественный язык, без
EN/RU-каши и без «лог-заголовков»). Перед отправкой хода — **prose-self-check**
(§3 «Prose на каждом ходе»). Фиксации слоёв и запись `project.md` — полный
цикл prose (subagent → `PASS`). Без `PASS` в файл не писать.

**Форма диалога — сократовская, академическая, послойная:** не сваливать
дерево в Frame A/B/C. Слой problem → cause/hyp → method; на каждом слое
несколько вопросов. Постоянно сверять литературу ↔ ответы исследователя ↔ код,
но формулировать сверку **человеческим академическим языком**, не мета-жаргоном
агента (`gap`, `claim`, `KOI-узел`, `falsification`, сырые англ. title без
перевода смысла).

## Когда запускать

1. «Подключи `<path>` к ResearchOS» / «onboard» / «attach repo».
2. Репозиторий лежит рядом с engine (или в `KOI_SCAN_ROOTS`), код есть,
   нет `tree/<repo>/koi-structure/project.md` (и нет legacy
   `<repo>/koi-structure/project.md`).
3. Человеку сложно самому сформулировать верхнеуровневую problem/cause.

**Не** запускать, если:

- дерево уже есть и нужна новая карточка → **koi-grill-experiment**;
- нужен полный Intro/Related Work / BibTeX → **literature-review-agent**
  (PaperOrchestra Step 3);
- нужен только layout / ветка sync без диалога →
  `python -m koi.projects.install_cli install <repo>`;
- нужен только git-sync уже подключённого проекта → **koi-project-sync**.

## Пайплайн (обязательный порядок)

```text
0 Prefight (+ скан соседних проектов/программ) → 1 Code scan → 2 Lit framing
→ 3A Сократ PROBLEM (≥4 вопроса) → prose-фиксация
→ 3PROG Сократ PROGRAM (≥1–2 вопроса) → фиксация programs:
→ 3B Сократ CAUSE+HYP (≥4 вопроса) → prose-фиксация
→ 3C Сократ METHOD (≥3 вопроса, seed cards) → prose-фиксация
→ 5 Clarity loop (холодный читатель заголовков, ≤6) → лучший набор titles
→ 6a prose-pass → 6b Write в tree/<repo>/koi-structure/ (только после «пиши»)
→ 6c install_cli + sync push (если у репо есть .git) → handoff
```

Не пиши `koi-structure/`, пока не закрыты слои 3A → 3PROG → 3B → 3C,
не пройден clarity loop (§5) и человек не сказал «пиши». Не перескакивай со
слоя problem сразу к method. Если репозиторий — git, после записи **обязательно**
§6c (`install_cli`).

---

## 0. Prefight

1. Разреши путь к **code-репо** (абсолютный или относительно workspace). Каталог
   должен существовать. Имя папки = `<repo>` для `tree/<repo>/`.
2. Discovery: репо — sibling engine (`parent(ENGINE_ROOT)/<repo>`) или путь из
   `KOI_SCAN_ROOTS`. Если путь вне scan roots — предупреди: UI может не увидеть
   проект, пока корень не добавят в scan.
3. Если уже есть `tree/<repo>/koi-structure/project.md` **или** legacy
   `<repo>/koi-structure/project.md` — **не перезаписывать**. Предложи: выйти /
   точечно дополнить дерево (отдельная сессия) / показать текущий skeleton /
   только `install_cli migrate` если дерево есть, но не в `tree/`. По умолчанию —
   стоп.
4. **Соседние проекты и программы** (для слоя 3PROG): в том же parent найди
   `tree/*/koi-structure/project.md` и legacy `*/koi-structure/project.md`.
   Из frontmatter каждого собери список программ (`programs:` — `id` + `title`
   или строковый id). Внутренний список `existing_programs[]` + какие проекты
   в них входят. Не спрашивай об этом до фиксации problem (§3A).

---

## 1. Code scan (без вопросов к человеку)

Три прохода. Не спрашивай то, что видно в файлах.

| Проход | Где смотреть | Что извлечь |
|--------|--------------|-------------|
| **Intent** | README, abstracts, paper drafts, top-level dirs | кандидат phenomenon / problem |
| **Stakes** | reward/loss, env wrappers, ablation flags, curriculum | кандидаты remediation / method |
| **Evidence** | `examples/`, `*-jobs/`, train/eval scripts, log hints | seed-карточки backlog |

Выход (внутренний черновик, 5–10 bullets):

- что делает репо;
- ставки (что уже пробуют менять);
- как запускают проверки;
- явные gaps (README говорит OOD, jobs только in-domain — и т.п.).

**Запрет:** называть problem именем метода/фичи из репо («diversity bonus»,
«LoRA PPO»). Method ≠ problem. См. framing-checks.

---

## 2. Literature framing scan (лёгкий)

Цель — помочь сформулировать **явление и причины**, не написать Related Work.

**Не** вызывай полный `literature-review-agent` (BibTeX, Intro, 20–30 calls).

1. Из code scan сформулируй 4–6 поисковых запросов:
   - 2–3 на **явление / failure mode / gap**;
   - 2–3 на **механизмы / причины**, которые поле обсуждает;
   - опционально 1–2 survey / position paper.
2. Найди кандидатов через web search; при доступности — Semantic Scholar
   `paper/search` (без полной верификации PaperOrchestra, без Crossref-пайплайна).
3. Оставь **5–12** релевантных papers. На каждый — одна строка:
   title, year, *как формулируют problem*, *какую cause предполагают*,
   *какое вмешательство* (если есть).
4. Внутри себя держи **банк вариантов** (не показывай целиком как «выбери
   Frame A/B/C»):
   - 2–3 кандидата **problem** из lit+кода;
   - 2–4 кандидата **cause** и связанных hyp;
   - 1–3 кандидата **method** из jobs.
   Метки `code+lit` / `code-only` / `lit-only` — для себя; в диалоге
   раскрывай по мере слоя.

Правила grounding — в [framing-checks.md](framing-checks.md).

---

## 3. Сократовский диалог (академический ритм)

Цель — совместно сформулировать **проблему, причины, гипотезы и методы**
в терминах области, опираясь на литературу, код и позицию исследователя.
Это не терапевтическое интервью и не коучинг.

**Запрещённый тон:** «что болит», «как вы себя чувствуете», «что для вас
важнее эмоционально», «своими словами без модулей» как единственный фокус.
**Нужный тон:** research interview — постановка проблемы, вклад в область,
сопоставление с prior work, механизм, способ проверки.

### Prose на каждом ходе (обязательно)

Перед отправкой **любого** сообщения человеку:

1. Напиши черновик хода.
2. Прогони **prose-self-check** по [`../koi-prose-style/SKILL.md`](../koi-prose-style/SKILL.md)
   и [framing-checks.md](framing-checks.md) § «Prose в диалоге»:
   - русский как основной язык фразы;
   - англ. термин — только после русской расшифровки, в скобках;
   - название статьи можно оставить, но **смысл постановки** — по-русски;
   - нет сырого пайплайн-жаргона (`validate`, `trace`, `step()`, `gap`,
     `claim`, `KOI-узел`, `category error`) в тексте для человека;
   - сверка читается как абзац рассуждения, не как лог полей.
3. Если self-check не проходит — перепиши **до** отправки. Не отправляй
   «техническую сверку» в надежде, что человек поймёт.
4. На **фиксации слоя** и перед записью файла — полный цикл
   **koi-prose-style** (subagent → `PASS`), не только self-check.
5. Внутренние notes агента могут быть жаргонными; в чат они не попадают.

Плохой ход (так писать нельзя) и хороший — в framing-checks § «Prose в диалоге».

### Триангуляция на каждом ходе (обязательно)

Каждый ход после первого ответа связывает три источника, но **языком prose**:

1. **Литература** — 1–3 работы: авторы/год + по-русски, как они ставят проблему
   или причину.
2. **Позиция человека** — парафраз его тезиса простым академическим языком.
3. **Код репо** — что уже измеряют или меняют, без имён флагов в зачине.

Смысл сверки (содержание), не ярлыки:

```text
Вы говорите, что … Это близко к работе «…» (Year), где … .
От работы Author et al. (Year) ваша постановка отличается тем, что … .
В коде проекта это видно так: … .
Отсюда для формулировки проблемы следует: … .
```

Без такой сверки следующий вопрос не задавай вхолостую. Блоки-ярлыки
`Сверка:`, `Комментарий:`, `⟨согласуется|…⟩` **не использовать** — пиши
связным текстом.

### Правила хода

1. **Один вопрос за сообщение.** Не анкетой.
2. **Минимум вопросов — нижняя граница, не квота.** Не закрывай слой после
   формального числа вопросов: закрывай только после `PASS` смысловых ворот
   из [framing-checks.md](framing-checks.md) § «Ворота готовности узлов».
3. Вопрос предваряй контекстом из работ и кода — уже в prose.
4. Вопрос — про исследовательскую позицию: схожая ли проблема с prior work;
   почему её стоит решать; какой вклад в область; какой механизм; как проверить.
5. После каждого ответа сначала определи, **что фактически сказал** человек:
   наблюдаемое явление, механизм, ожидаемое наблюдение, вмешательство или
   протокол. Не доверяй предложенному им названию типа узла автоматически.
6. Проверь полноту ответа и связь с родителем. Если ответ короткий, расплывчатый,
   смешивает типы или не проходит хотя бы один обязательный критерий — не
   переходи к следующему пункту интервью. Назови один главный дефект и задай
   один точный уточняющий вопрос по недостающему компоненту.
7. Исследователь отвечает за предметный смысл; агент — за классификацию,
   проверяемость и качество формулировки. Не спрашивай «это cause или
   remediation?»; выясни смысл обычным научным вопросом и выбери тип сам.
8. После ответа — следующий ход: prose-сверка → один следующий вопрос.
9. Дождись ответа. Не генерируй Q[k+1] в том же сообщении.
10. В конце слоя предложи title + описание, перечисли оставшуюся
    неопределённость, если она есть, и попроси подтвердить **смысл**, а не
    терминологию KOI. Фиксируй слой только при `PASS`.
11. **Pushback академический, конкретный:** не соглашайся с плохой
    формулировкой из вежливости. Укажи, какой критерий нарушен, почему это
    ломает ветку, предложи 1–3 правдоподобные интерпретации из литературы/кода
    и задай один вопрос, который их различает.
12. Не додумывай недостающий предметный факт. Можно предложить формулировку как
    гипотезу агента, но явно попросить исследователя подтвердить или исправить.

После каждого содержательного ответа выполняй внутренний цикл:

```text
классифицировать фактический смысл
→ проверить полноту узла
→ проверить тип
→ проверить связь с родителем
→ выбрать один главный дефект
→ дать короткий академический pushback
→ задать один уточняющий вопрос
→ повторять до PASS
```

Короткий ответ не является ошибкой сам по себе. Ошибка — принять его, когда
по нему нельзя построить проверяемый узел. Например, «плохая генерализация»
задаёт тему, но ещё не problem: уточни объект, между какими условиями возникает
разрыв и как он наблюдается.

Формат хода (содержание; стиль — как у живого исследователя):

```text
[слой problem · вопрос 2 из 4]

В близких работах проблему часто ставят так:
- «Название» (Year) — …
- «Название» (Year) — …

Вы ранее сказали, что … . Это сходится с первой постановкой и расходится со
второй в том, что … . В вашем репозитории это отражается так: … .

Считаете ли вы, что решаете схожую проблему — или ваша постановка другая?
```

Банк вопросов — [framing-checks.md](framing-checks.md) § «Сократовские слои».

---

### 3A. Слой PROBLEM (сначала только он)

Бриф (одно сообщение, без вопросов, уже в prose): 3–5 пунктов по репо +
2–4 работы — как в близких работах формулируют проблему (наблюдаемое явление
или пробел), без причин и методов.

Затем **по одному** минимум **4 вопроса**:

| # | Зачем | Пример вопроса (тон) |
|---|-------|----------------------|
| P1 | Сопоставление с prior work | В проектах, близких к вашему, проблему часто ставят так: (1) … (2) … — считаете ли вы, что решаете **схожую** проблему, или ваша постановка другая? |
| P2 | Мотивация / необходимость | Почему эту проблему, на ваш взгляд, **нужно** решать сейчас — какой пробел в результатах или теории она закрывает? |
| P3 | Вклад в область | Если эту постановку удастся закрыть, **чем это продвинет** область (обучение агентов, перенос на новые среды, …)? Какой результат вы готовы отстаивать? |
| P4 | Границы постановки | Какие соседние формулировки из литературы вы **намеренно не** берёте в корень (слишком широко, другая программа, уже закрыто ранее)? |
| P5 | (если нужно) Условия проявления | В каких условиях или на какой задаче отсутствие прогресса по этой проблеме видно яснее всего? |

Стоп слоя: согласованный **problem** (title + описание) после prose-pass и
`PASS` ворот problem. В частности, должны быть известны объект, наблюдаемое
явление, условия, ожидаемое сравнение и значимость; причина и решение не
должны быть спрятаны в формулировке.
Обнови черновик брифа: секции «цель/вклад», «Problem», «Опорная литература»,
«Границы» (в рабочей памяти или сразу во временный файл; на диск в
`koi-structure/` — не раньше согласия «пиши», либо пиши draft в
`<repo>/.koi-onboard-brief.draft.md` вне sync, если удобно держать на диске
раньше). Cause, program и method не обсуждать, пока problem не зафиксирован.

---

### 3PROG. Слой PROGRAM (исследовательская программа)

Только после фиксации problem. Программа — организационный слой **над**
проектом (группа в сайдбаре UI); членство пишется в frontmatter
`programs:` ([program-format](../../../docs/human/program-format.md), ADR-001).

Контекст хода (prose): зафиксированная проблема + что уже есть у соседей.

**Если `existing_programs` не пуст** (соседние репо с `koi-structure/` на том
же уровне уже указывают программы):

| # | Зачем | Пример вопроса |
|---|-------|----------------|
| R1 | Принадлежность | Рядом уже есть проекты ResearchOS в программах: (1) «…» (проекты: …) (2) «…». Входит ли **ваш** проект в одну из них — или это отдельная программа? |
| R2 | (если «отдельная» / «нет») | Тогда зададим новую. По литературе и вашей постановке проблемы напрашиваются такие рамки программы: (1) … (2) … (3) … — какую берём, или напишите свою формулировку (короткий title ≤ 8 слов)? |

**Если соседних программ нет:**

| # | Зачем | Пример вопроса |
|---|-------|----------------|
| R1 | Новая программа | Проект в UI группируется по **исследовательской программе**. По близкой литературе к вашей проблеме варианты: (1) … (2) … (3) … — выберите или напишите свою (title ≤ 8 слов). Можно явно сказать «без программы». |

Правила:

1. Один вопрос за ход; сверка lit ↔ ответ — в prose.
2. Варианты из литературы — **стратегическая рамка** (область / линия работ),
   не название метода и не копия problem title.
3. `id` программы: kebab-case / транслит от title (латиница или кириллица как
   у соседей; согласуй со стилем `existing_programs`).
4. В frontmatter пиши:

```yaml
programs:
  - id: <program-id>
    title: <короткий title ≤ 8 слов>
```

5. Если человек сказал «без программы» — поле `programs:` не добавляй.
6. Prose-self-check на title программы.

Стоп слоя: зафиксированный `programs:` (или явное «без программы») → обнови
бриф (секция Program) → 3B.

---

### 3B. Слой CAUSE + HYPOTHESES

Только после фиксации problem **и** слоя PROGRAM. Напомни зафиксированную
проблему одной фразой и 1–2 lit-якоря, которые её поддерживают или оспаривают.

Задай **по одному** минимум **4 вопроса**:

| # | Зачем | Пример вопроса (тон) |
|---|-------|----------------------|
| C1 | Механизм | Какой **механизм** (причина), по вашей гипотезе, порождает зафиксированную проблему — в отличие от выбора конкретного алгоритма? |
| C2 | Сопоставление с lit | В работах по близкой теме причины формулируют как … / … — ваша причина **совпадает**, уточняет или противоречит им? |
| C3 | Falsifiability | Какой исход эксперимента заставил бы вас **отклонить** эту причину? |
| C4 | Evidence vs remediation | Если причина верна, какое наблюдение вы ожидаете увидеть — или какое изменение системы, по-вашему, должно ослабить этот механизм? |
| C5 | (если remediation) | Почему выбранное вмешательство должно действовать именно на названный механизм — какая каузальная связь? |
| C6 | (если 2 cause) | Какую причину ставим первой в дереве и почему не параллельно? |

Каждый ответ снова сверяй с lit и с уже зафиксированным problem.

Стоп слоя: 1–2 **cause** + 1–2 **hyp**, прошедшие собственные ворота и
проверку связей `problem ← cause ← hyp`; затем prose-фиксация и confirm.
`cause` считай объяснительной гипотезой. `cause_evidence` — ещё не полученное
доказательство, а ожидаемое наблюдение, если cause верна. `remediation` —
проверяемая гипотеза вмешательства.
Обнови бриф: Cause, Hypothesis (с типом).

---

### 3C. Слой METHOD (+ seed cards)

Только после фиксации cause/hyp.

Контекст: протоколы из lit + сравнения, уже заложенные в jobs репо — как
кандидаты **experimental protocol**, не как имена фич.

Задай **по одному** минимум **3 вопроса**:

| # | Зачем | Пример вопроса (тон) |
|---|-------|----------------------|
| M1 | Design | Какой протокол проверки вы считаете адекватным: что варьируете, что контролируете, какой baseline? |
| M2 | Decision rule | По какой основной метрике и при каком пороге/направлении эффекта гипотеза будет поддержана или отвергнута? |
| M3 | Сопоставление | В литературе и в ваших запусках встречаются протоколы … / … — что берём как method, что оставляем за скобками? |
| M4 | Seed | Какие 0–3 уже существующих запуска зафиксировать в backlog как черновые карточки (без полной миграции истории)? |

Стоп слоя: 1–2 **method**, где зафиксированы сравнение, контроль, измерение и
правило интерпретации, + 0–3 seed cards; prose-фиксация; показать всю причинную
цепочку на финальный confirm. Дополни бриф: Method (без имён модулей).

Глубина v1: 1 problem, 1–2 cause, 1–2 hyp, 1–2 method, 0–3 seed cards.
Дальнейшая детализация карточек → **koi-grill-experiment**.

Перед §5 собери полный черновик брифа (все секции шаблона). Он станет
`onboard-brief.md` при записи (§6b) и уже используется как ANCHOR в §5.

---

## 5. Clarity loop — холодный читатель **заголовков** (обязательно)

После фиксации skeleton (и confirm человека «можно полировать / писать») —
цикл понятности **только по заголовкам** узлов/карточек/программы. Описания
и `desc:` в цикл **не входят** (без лимита слов; не показываются cold reader).

Цель: titles на карте понятны незнакомому читателю **и** остаются на уровне
согласованных в диалоге высоких проблем/целей — не сползают в пайплайн и
отладку. Максимум **6** итераций.

### Якорь = `onboard-brief.md` (для Writer, запрещён cold reader)

Перед циклом Writer обязан иметь актуальный бриф (черновик или уже
`koi-structure/onboard-brief.md`). Это и есть **ANCHOR**.

На **каждой** итерации до правки titles:

1. Перечитай бриф целиком (секции цели, problem, cause, hyp, method).
2. Только потом готовь `T_i` / правь после критики.
3. Бриф **не** клади в промпт cold reader.

| Разрешено | Запрещено (дрифт) |
|-----------|-------------------|
| Уточнить явление/механизм/идею вмешательства тем же уровнем абстракции | Подменить problem на шаги конвейера («отслеживание → связи → важность») |
| Сделать title понятнее без жаргона кода | Уйти в отладку кадров, сегментацию, «полный конвейер vs …» как problem/cause |
| Method = протокол проверки идеи | Method/cards = список инженерных тасков вместо научной проверки |

Если cold reader просит «конкретнее» — конкретизируй **научную постановку**
по брифу, а не реализацию в репо. Если titles начинают расходиться с брифом —
либо верни titles к брифу, либо (редко, после согласия человека) обнови бриф
и снова прогони clarity; молча «переехать» на пайплайн нельзя.

### Плохо vs хорошо (уровень абстракции)

❌ Плохо (дрифт в пайплайн после «уточнений»):

```text
problem: Модель не группирует фигуры в головоломках и плохо планирует
cause: На упрощённых кадрах фигуры не группируются
remediation: Конвейер: отслеживание → связи фигур → важность
method: Полный конвейер vs сегментация: с моделью мира и без
cards: Отладить отслеживание… · Связать одинаковые фигуры… · Добавить важность…
```

✅ Хорошо (держится высоких целей диалога):

```text
problem: Модели не рассуждают в абстрактных визуальных средах
cause: Нет модели для рассуждений в абстрактных сценах
remediation: Правила гештальта и внимания человека
method: Модель мира на гештальте и внимании
```

(Карточки могут быть конкретнее method, но не должны перетягивать problem/cause
вниз к отладке.)

### Роли

| Роль | Кто | Делает |
|------|-----|--------|
| **Writer** | агент онбординга | правит **только заголовки**; держит `ANCHOR`; не объясняет в чат |
| **Cold reader** | новый subagent | видит **только** titles; не знает `ANCHOR`, репо, диалог |

### Снимок для cold reader (только titles)

```text
problem: <title>
  cause: <title>
    remediation|cause_evidence: <title>
      method: <title>
        cards: <card title>, …
program: <title>
project_title: <frontmatter title>
```

Без описаний, кода, lit, `ANCHOR`, пояснений.

### Итерация `i = 1..6`

1. Writer готовит `T_i` (+ сверяет с `ANCHOR` до отправки).
2. Cold reader (`generalPurpose`, readonly, `KOI titles cold read`):

```text
You are a cold reader. You know nothing except the TITLE tree below.

Task: which titles are unclear, ambiguous, or too jargon-heavy on a map?

Do NOT ask for implementation details, pipelines, or module names.
Prefer feedback that keeps titles as research claims (phenomenon / mechanism /
idea), not engineering task lists.

Output:
Line 1: CLEAR or UNCLEAR
If CLEAR: one sentence; clarity 1-10; laconicism 1-10.
If UNCLEAR: Title | What is unclear | What would help
  (do NOT rewrite; do NOT ask for descriptions).

Titles:
<paste T_i only>
```

3. Ранний стоп: `CLEAR` и clarity ≥ 8 и laconicism ≥ 7.
4. При `UNCLEAR`:
   - Writer меняет **только titles** → `T_{i+1}`;
   - перед принятием `T_{i+1}` — **anchor-check** (ниже);
   - нельзя чинить через описание/`desc` или чат-пояснения.
5. Лимит: ≤ **8** слов; критический title после двух провалов — до **≤ 12**.
6. Prose-self-check на titles после каждой правки.

### Anchor-check (после каждой правки Writer)

Ответь себе да/нет (внутренне; при любом «нет» — перепиши titles заново):

1. Problem всё ещё про **явление/пробел области**, согласованный в 3A — не про
   кадры/конвейер/отладку?
2. Cause — **механизм**, а не упрощение датасета или баг трекера?
3. Hyp — **идея вмешательства/доказательства** из 3B, а не список модулей?
4. Method — **как проверить идею**, а не «полный пайплайн vs сегментация» как
   замена problem?
5. Новые titles можно кратко сопоставить с `ANCHOR` одним предложением каждое?

Дрифт (как в плохом примере выше) = кандидат `T_{i+1}` **бракуется**, даже если
стал «понятнее» cold reader за счёт конкретики пайплайна.

### Выбор лучшей версии

Сравни `T_1…T_k` по: (1) понятности, (2) лаконичности, (3) **верности `ANCHOR`**,
(4) меньше исключений 9–12 слов. Кандидат с дрифтом отбрасывай.

Зафиксируй лучшие titles; описания оставь из диалога (подгони под titles вне
цикла при §6a). Кратко человеку: итерации + что изменилось в titles.

Если на 6-й всё ещё `UNCLEAR` без дрифта — покажи замечания и спроси человека.
Без «пиши» файл не пиши.

---

## 6. Финальный prose-pass + запись (только после «пиши» / «создавай»)

### 6a. Обязательный prose-pass на skeleton

Собери **все** видимые фрагменты из **лучшей** версии после §5:

- frontmatter `title`, `description`;
- заголовок и описание каждого узла (problem, cause, hyp, method);
- заголовки и `desc:` seed-карточек канбана.

Уже зафиксированные тексты прогони ещё раз целиком (consistency).
Для title с пометкой `title_words:9-12` — допустимо ≤12 слов; иначе ≤8
(`koi-prose-style`).

Запусти полный цикл **koi-prose-style** → только при `PASS` переходи к 6b.
После 3× `FAIL` — покажи таблицу замечаний и спроси; **не пиши файл** без
явного согласия сохранить как есть.

В ответе пользователю после записи: «стиль проверен (koi-prose-style), N итераций».

### 6b. Запись на диск

Пиши в **канонический** путь (создай каталоги при необходимости):

```text
tree/<repo>/koi-structure/
  project.md
  onboard-brief.md       # из шаблона onboard-brief.template.md + итог диалога
  research.json          # {"version": 1, "questions": []}
  reports/               # пустой каталог (или .gitkeep)
```

где `tree/` — sibling engine (`parent(ENGINE_ROOT)/tree/`), `<repo>` — имя
папки code-репо. Не клади skeleton в `<repo>/koi-structure/`, если можно сразу
в `tree/` (иначе §6c смигрирует).

`onboard-brief.md` пиши **до или вместе** с `project.md`, заполненный по
итогу слоёв и (если titles чуть уточнялись в §5 без смены смысла) согласованный
с финальными titles. Удали draft `.koi-onboard-brief.draft.md`, если был.
Файл уходит в orphan-sync вместе с остальным `koi-structure/`.

### `project.md` frontmatter

```yaml
---
id: <slug-from-folder-or-agreed-id>   # латиница, kebab-case; не имя папки обязательно, но обычно совпадает
title: <короткий заголовок problem — после prose-pass>
description: <1–3 предложения — после prose-pass>
updated: <ISO-8601 Z>
format: koi/1
git_repo: true                    # если есть <repo>/.git; иначе false / опустить и пропустить §6c
git_sync_branch: koi/research     # default; другой — только если человек явно назвал
programs:                         # из слоя 3PROG; опустить, если «без программы»
  - id: <program-id>
    title: <title ≤ 8 слов>
---
```

Если `<repo>/.git` есть — **всегда** ставь `git_repo: true` и
`git_sync_branch` (по умолчанию `koi/research`). Без этих полей CLI sync
не подхватит mount.

### Дерево

- Заголовки: `# problem: <id>`, `## cause: <id>`, `### remediation:` или
  `### cause_evidence:`, `#### method: <id>`.
- Id: короткие осмысленные (`problem`, `c-…`, `r-…`, `m-…`) или вид `n-…` /
  `c-…` как в существующих проектах. Id — технические; **видимый** текст рядом
  с ними — только prose.
- Под каждым method — kanban-таблица:

```markdown
<!-- koi:kanban board-<method-id> -->
| backlog | running | done | successful |
| --- | --- | --- | --- |
| <человекочитаемый title> <!-- id:<card-id> desc:<выход эксперимента; путь к скрипту можно в конце> --> |  |  |  |
```

- `verdict:` на cause не ставь при онбординге (всё `open` по умолчанию).
- Текст узлов — проверяемые утверждения **и** естественный язык (оба требования).
- Заголовок узла / карточки — **≤ 8 слов**; всё остальное — в описании или `desc`
  (видно при открытии в UI).

### Чеклист перед записью

- [ ] Prefight: нет существующего `project.md` (или явное «дополнить»)
- [ ] Закрыты слои 3A → 3PROG → 3B → 3C (problem, program, cause/hyp, method)
- [ ] `programs:` записан по итогам 3PROG или явно опущен («без программы»)
- [ ] `koi-structure/onboard-brief.md` записан и согласован с диалогом
- [ ] Clarity loop §5: ≤6 итераций по titles; сверка с brief; нет дрифта в пайплайн
- [ ] Type-checks framing-checks пройдены на каждом узле
- [ ] **koi-prose-style: PASS** на всех видимых фрагментах skeleton
- [ ] Заголовки ≤ 8 слов (или ≤ 12 только на критических узлах после §5)
- [ ] Нет EN/RU-каши и «лог-заголовков» (validate fail, trace, OOM в title)
- [ ] 1 problem / ≤2 cause / ≤2 hyp / ≤2 method (или явный expand)
- [ ] Method ≠ название фичи без протокола сравнения
- [ ] `research.json` валидный JSON
- [ ] `git_repo` / `git_sync_branch` согласованы с наличием `.git`

После записи: если есть `.git` — сразу §6c. Иначе кратко скажи путь к
`project.md`, `id`, что сделать в UI, следующий шаг.

---

### 6c. Layout + orphan-ветка (`install_cli`, если git-репо)

**Когда:** у `<repo>` есть `.git` и в frontmatter `git_repo: true`.
**Не когда:** локальная папка без git — достаточно записи в
`tree/<repo>/koi-structure/`; sync недоступен.

Цель: research-данные на **orphan-ветке** (`git_sync_branch`, default
`koi/research`) и рабочая копия в `tree/<repo>/` (worktree), не в истории
code-ветки. Не меняй `git config`. Не коммить `.env` и секреты.

Из **корня engine** (`ReseachOS/`) — предпочтительно одной командой:

```bash
# повесить/создать koi/research → tree/<repo>/koi-structure
python -m koi.projects.install_cli install <repo>

# дослать свежий skeleton на sync-ветку (если install ещё не запушил)
python -m koi.projects.sync_cli push --project-id <id> \
  --message "projects(<id>): onboard skeleton tree"

python -m koi.projects.sync_cli status
# при необходимости: python -m koi.projects.install_cli status
```

`install_cli` сам: создаст orphan при необходимости, добавит worktree в
`tree/<repo>`, пропишет ignore на code-ветке, смигрирует legacy
`<repo>/koi-structure` или `.koi-sync-worktree`.

Если `install` / `push` падает (нет `origin`, нет прав, non-fast-forward):

- покажи stderr;
- **не** делай `--force`;
- предложи человеку починить remote / права и повторить
  `python -m koi.projects.install_cli install <repo>` /
  `python -m koi.projects.sync_cli push --project-id <id>`;
- локальный `tree/<repo>/koi-structure/` при этом уже записан — онбординг не
  откатывай.

В финальном ответе человеку (prose): путь к
`tree/<repo>/koi-structure/project.md`, `id`, имя orphan-ветки, что
`install_cli`/`push` прошли или какая ошибка, что открыть в UI после
`./scripts/koi-serve.sh restart` при необходимости.

---

## 7. Handoff

| Дальше | Скилл |
|--------|--------|
| Расписать карточку до прогона | **koi-grill-experiment** — перед новыми titles узлов перечитай `tree/<repo>/koi-structure/onboard-brief.md` |
| Прогнать карточку | **koi-execute-card** |
| Длинный прогон / remote с ролями | **koi-card-autoresearch** (+ project-скилл запуска, если есть) |
| Дальнейший sync | **koi-project-sync** / `sync_cli push|pull` (working copy в `tree/`) |
| Только layout / migrate | `python -m koi.projects.install_cli install|migrate <repo>` |
| Полный Related Work для статьи | **literature-review-agent** / paper pipeline |

Любая поздняя правка заголовков в `project.md` — сначала
`onboard-brief.md`, потом title.

Стиль при онбординге закрыт **koi-prose-style** на фиксациях слоёв и в §6a;
отдельно «потом прогнать prose» не откладывать.

---

## Вне scope v1

- Автосоздание программы в UI
- Миграция старых отчётов / wandb runs в `done`
- Перезапись существующего дерева
- Полный BibTeX / Intro / citation F1
- Force-push orphan/code веток

## Связанные документы и скиллы

- Бриф-якорь: [onboard-brief.template.md](onboard-brief.template.md) →
  `tree/<repo>/koi-structure/onboard-brief.md`
- Стиль UI-текста (обязательный gate): `agents/skills/koi-prose-style/SKILL.md`
- Install / migrate layout: `python -m koi.projects.install_cli`
- Orphan sync CLI: `python -m koi.projects.sync_cli` · skill `koi-project-sync`
- Discovery: `docs/adr-001-project-discovery.md` · `AGENTS.md` § Layout
- Attach (human): `README.md` § «Add a project» · `docs-site/start/with-code.html`
- Формат дерева: `docs/human/project-format.md`
- Словарь узлов: `docs/human/getting-started.md` (§3–§5, §0a)
- Grill карточки: `agents/skills/koi-grill-experiment/SKILL.md`