# Ruflo Queen Trigger + расширенная делегация — Design Spec

**Дата:** 2026-05-15
**Статус:** дизайн одобрен заказчиком (через `superpowers:brainstorming`, 6/6 секций)
**Экономия:** 0% (максимальное качество, без скипов)
**Связанные артефакты:** `tools/ruflo-recall-hook.mjs`, `tools/ruflo-h7-patch.mjs`,
`docs/Pravila_raboty_Claude_v1_1.md`, `~/.claude/hooks/economy-mode.py` (прецедент trigger-хука)

---

## 1. Контекст и проблема

Ruflo (v3.7.0-alpha.38, ex-Claude-Flow) интегрирован в стек Лидерры на нормативном
уровне: 4 normative-файла объявляют ruflo «уровнем −1, Queen-led routing entry-point».
Runtime активирован — daemon под PM2, hive-mind (Queen + 9 agents), память + embeddings.

**Но это paper-level.** Фактически сессия Claude Code не маршрутизируется через Queen
ruflo: Claude Code — реальный entry-point, ruflo присутствует лишь как (а) пассивный
advisory recall-хук, (б) opt-in MCP-инструменты, (в) фоновый daemon. Ни одна задача
не «идёт через Queen».

Заказчик закрывает gap двумя деливераблами:

- **D1** — жёсткое правило: триггер-слова `queen`/`королева` в промпте → безусловный
  запуск задачи через ruflo Queen.
- **D2** — расширение нормативки: чаще делегировать нетривиальные задачи в ruflo.

## 2. Цель

Превратить «ruflo может быть задействован» в «queen/королева → ruflo задействуется
безусловно; нетривиальные задачи → ruflo предлагается проактивно» — с детерминированным
enforcement-хуком и нормативным hard-rule статусом, при сохранении контроля расхода денег.

## 3. Согласованная семантика (5 решений заказчика)

| # | Вопрос | Решение |
|---|---|---|
| 1 | Что делает «через ruflo»? | `hive-mind spawn --claude` — реальные платные параллельные Claude-агенты |
| 2 | Контроль расхода | Превью (агенты, scope, оценка) → спавн после явного «да» |
| 3 | «Чаще через ruflo» | Расширить авто-предложение spawn на задачи и без слова queen |
| 4 | Граница задач | Нетривиальные → spawn; тривиальные → напрямую. **НО** слово queen — закон: с триггером маршрут к ruflo безусловен, тривиальность не отменяет |
| 5 | Подход | Отдельный хук `tools/ruflo-queen-hook.mjs` + новый Pravila §14 |

**Разрешение напряжения «queen = закон, сразу» vs «превью+подтверждение»:** слово queen —
закон о **маршрутизации** (задача безусловно идёт к ruflo Queen, Claude не оспаривает).
Превью+подтверждение — **cost-gate** на объём/деньги, не veto маршрута. «Сразу» = Claude
немедленно принимает ruflo-маршрут и немедленно готовит превью; «подтверждение» = одно
«да» на расход.

## 4. Архитектура

Три части:

1. **Детект-хук** `tools/ruflo-queen-hook.mjs` — `UserPromptSubmit`, матчит триггер,
   инжектит жёсткую директиву в `additionalContext`.
2. **Поведенческая модель** — что Claude делает при триггере / без триггера / на тривиальном.
3. **Нормативка** — Pravila §14 (новый explicit hard-rule) + §13.6 tier-таблица + §0;
   CLAUDE.md §1/§3.5; точечный cross-ref в PSR_v1/Tooling.

Поток данных: `UserPromptSubmit` → хук получает prompt по stdin → строковый матч
триггера с guard'ами → при матче `stdout` = `additionalContext` с директивой → Claude
видит директиву безусловно → route к ruflo Queen.

## 5. Компонент A — хук `tools/ruflo-queen-hook.mjs`

### 5.1. Тип и регистрация

`UserPromptSubmit`-хук, Node ESM (`.mjs`), консистентно с `tools/ruflo-*.mjs`.
Регистрируется вторым элементом массива `hooks.UserPromptSubmit` в `.claude/settings.json`
рядом с существующим `ruflo-recall-hook.mjs` (оба хука выполняются на каждый промпт;
queen-хук — чистый строковый матч без subprocess, latency микросекунды).

### 5.2. Детекция триггера

Функция `detectQueen(prompt) -> boolean`:

- **Английский:** `/\bqueen\b/i` — ASCII word-boundary корректен для латиницы.
- **Русский:** `королева` в формах а/у/е/ы/ой/ою — regex
  `/(?<!\p{L})королев(?:ой|ою|а|у|е|ы)(?!\p{L})/iu` — Unicode-aware границы слова
  через lookbehind/lookahead `\p{L}` (JS `\b` не работает с кириллицей).
- Матч **позиционно-независим** (в отличие от end-anchored `economy-mode.py`): заказчик
  пишет триггер и в начале («queen, сделай X»), и в конце.
- Срабатывает, если матчит **любой** из двух паттернов.

### 5.3. Guard'ы против meta-обсуждения

Функция `isDiscussion(prompt, matchIndex) -> boolean` — по образцу `economy-mode.py`:
если в ~30 символах перед матчем (в той же клаузе) есть disqualifying-префикс — матч
не активирует триггер. Список префиксов:

`что такое`, `что значит`, `как работает`, `как работают`, `не используй`,
`не активируй`, `не запускай`, `не пиши`, `пример`, `вместо`, `забудь про`.

**НЕ** блокируем все вопросы (в отличие от `economy-mode.py` question-guard): queen-задача
может быть вопросом — «queen, почему тесты падают?» обязан триггерить. Meta-вопрос
«что такое queen?» отсекается префиксом `что такое`, не общим «?»-правилом.

### 5.4. Инжектируемая директива

При активном триггере `additionalContext` =

```text
=== RUFLO QUEEN TRIGGER (Pravila §14 — hard rule) ===

Промпт содержит триггер «queen»/«королева». §14 — explicit hard-rule.

ПЕРВОЙ строкой ответа написать:
  `ruflo Queen — задача маршрутизируется через рой (Pravila §14)`

ОБЯЗАТЕЛЬНО на этот промпт:
1. Задача БЕЗУСЛОВНО идёт через ruflo Queen (`hive-mind spawn --claude`).
   Не оспаривать, не предлагать прямой путь, не ссылаться на тривиальность.
2. Перед платным спавном показать ПРЕВЬЮ: роли и число агентов, декомпозиция
   задачи, оценка объёма. Спавнить ТОЛЬКО после явного «да» заказчика.
3. При сбое `hive-mind spawn --claude` (ruflo alpha) — явно сообщить о сбое,
   затем выполнить задачу напрямую (фоллбэк).

§9 «Отступления» к §14 не применяется. Economy-режим §14 не override-ит.
Действует только на этот промпт.
```

Формат вывода — `buildHookOutput(ctx)`:
`{ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } }`.

### 5.5. Fail-open

Любая ошибка (битый stdin-JSON, исключение) → пустая инжекция, `exit 0`. Хук **никогда**
не блокирует промпт. Та же посту­ра, что у `ruflo-recall-hook.mjs`. Без триггера — пустой
stdout, `exit 0`. Без state-файла (YAGNI — директива одноразовая на промпт).

### 5.6. Экспорты и структура

Чистые экспортируемые функции для TDD: `parsePrompt(stdinRaw)`, `detectQueen(prompt)`,
`isDiscussion(prompt, matchIndex)`, `buildDirective()`, `buildHookOutput(ctx)` + `main()`.
`main()` вызывается только при прямом запуске (`import.meta.url` guard, как в recall-хуке).

## 6. Компонент B — поведенческая модель

| Ситуация | Поведение |
|---|---|
| `queen`/`королева` в промпте | **Закон.** Route к ruflo Queen. Превью (роли, декомпозиция, оценка) → `hive-mind spawn --claude` после «да». Тривиальность не отменяет — превью покажет минимальный рой |
| Без queen, нетривиальная задача (multi-file / ≥3 шага / фича-эпик) | Claude **проактивно предлагает** ruflo-spawn — то же превью; спавн после «да» |
| Без queen, тривиальная задача (§12.3 Pravila) | Напрямую, без ruflo |
| `hive-mind spawn --claude` упал | Явно сообщить о сбое → выполнить задачу напрямую (фоллбэк); не нарушение §14 |

## 7. Компонент C — нормативные изменения

### 7.1. Pravila §14 (полный черновик)

Новый раздел `## 14. Ruflo Queen routing — hard rule (триггер queen/королева)`:

- **§14.1 Принцип.** Триггер `queen`/`королева` → задача безусловно маршрутизируется
  через ruflo Queen. Claude не оспаривает, не предлагает прямой путь, не ссылается на
  тривиальность.
- **§14.2 Механизм и cost-gate.** Маршрут = `hive-mind spawn --claude`. Перед платным
  спавном — превью; спавн после явного «да». Превью+подтверждение — контроль расхода,
  не отмена маршрута.
- **§14.3 Расширенная делегация.** Без триггера Claude проактивно предлагает route к
  ruflo для нетривиальных задач (multi-file / ≥3 шага / фича-эпик).
- **§14.4 Исключения.** Тривиальные задачи (§12.3) без триггера → напрямую. С триггером
  §14.1 превыше — маршрут к ruflo сохраняется.
- **§14.5 Hard-rule статус.** §14 — explicit hard-rule наравне с §12; §9 не применяется;
  economy-режим не override-ит; игнорирование = нарушение уровня §12/§5. Отмена — только
  явным «не используй ruflo сейчас» / «без queen», на текущее действие.
- **§14.6 Соотношение с §12.** §14 — слой маршрутизации (кто получает задачу), §12 —
  слой дисциплины исполнения (какими skills работать). Не конфликтуют. Порядок — по
  CLAUDE.md §1 (ruflo уровень −1 > §12 уровень 0).
- **§14.7 Enforcement.** §14 поддержан хуком `tools/ruflo-queen-hook.mjs`. Хук
  гарантирует видимость директивы, физически не запускает spawn.
- **§14.8 Ревизия.** Откат — явным запросом «откати §14». Сбой `hive-mind spawn`
  (alpha) → фоллбэк на прямое выполнение, не нарушение.

### 7.2. Pravila §13.6 tier-таблица + §0

- §13.6 tier-таблица: +строка `Explicit hard-rule | §14 (Ruflo Queen trigger) | §14.5 | ❌ нет`.
- §0 priority note: упомянуть §14 в числе explicit hard-rule (рядом с §12).
- Шапка Pravila: version bump v1.14 → v1.15; §10 история версий +entry.

### 7.3. CLAUDE.md

- §1 priority chain: уровень −1 ruflo дополнить note про §14-триггер как часть ruflo-слоя.
- §3.5 «Off-phase orchestration: ruflo»: +абзац «Queen trigger» (триггер queen/королева
  → §14 Pravila → hook `ruflo-queen-hook.mjs`).
- Шапка: version bump (v2.0 → v2.1).
- **Канал правки CLAUDE.md:** через `claude-md-management` (§5 п.10) ИЛИ user-authorized
  exception в implementation plan (прецедент — ruflo big-bang Phase 3). Решается в плане.

### 7.4. PSR_v1 + Tooling

- PSR_v1: точечный cross-ref — ruflo Queen routing имеет §14-триггер; version bump.
- Tooling §4.10 «Orchestration layer (ruflo)»: +упоминание queen-триггера; version bump.

## 8. Честные ограничения

1. **Хук не исполняет spawn.** `UserPromptSubmit`-хук может лишь инжектить
   `additionalContext` или заблокировать промпт — передать управление он не может.
   «Жёсткость» §14 = принудительная инжекция директивы (невозможно не увидеть) +
   нормативный hard-rule вес (пропуск = нарушение). Не «механически невозможно пропустить».
2. **ruflo — alpha.** `hive-mind spawn --claude` может упасть (alpha-квирки: Tensor.location,
   HNSW-ghosts). Фоллбэк — прямое выполнение + явный репорт сбоя. Hard-rule не делает
   alpha-софт надёжным.
3. **Стоимость.** Каждый спавн — реальные деньги (платные LLM-сессии агентов).
   Превью+подтверждение — единственный тормоз. `$10/день` cap в `.env.local` относится
   к daemon-воркерам, не к spawn-агентам (они идут через standalone `claude` CLI).
4. **False positives.** Слово «queen» во вставленном тексте (название группы, англ.
   фраза) может ложно сработать. Митигация — guard'ы + превью-подтверждение (заказчик
   скажет «нет» на нерелевантное превью).
5. **economy-mode.py.** Глобальный economy-хук в тексте immunity называет только §12.
   §14-immunity задокументирована в Pravila §14.5, но глобальный хук её не назовёт без
   правки `~/.claude/hooks/economy-mode.py` — см. §10 (опционально).

## 9. Тестирование

TDD, `node --test`, файл `tools/ruflo-queen-hook.test.mjs` (как `ruflo-h7-patch.test.mjs`
и `ruflo-recall-hook.test.mjs`). Кейсы:

1. `detectQueen('queen, fix the bug')` → `true`.
2. `detectQueen('сделай это через королеву')` → `true`.
3. `detectQueen('КОРОЛЕВА, подними рой')` → `true` (case-insensitive).
4. `detectQueen('several queens')` → `false` (word-boundary: «queens» ≠ «queen»).
5. `detectQueen('почини очередь задач')` → `false` (нет триггера; «очередь» ≠ «королева»).
6. `isDiscussion('что такое queen?')` для матча queen → `true` (guard).
7. `isDiscussion('как работает триггер queen')` → `true` (guard).
8. `isDiscussion('не используй queen сейчас')` → `true` (guard).
9. `detectQueen('queen, почему падает тест?')` без discussion-префикса → триггерит
   (вопрос-задача, не meta-обсуждение).
10. `buildDirective()` содержит `Pravila §14` и `hive-mind spawn`.
11. `buildHookOutput(ctx)` — корректная форма `hookSpecificOutput`.
12. `parsePrompt('{битый json')` → `''` (fail-open).
13. `main()` без матча → пустой stdout.

Нормативные файлы — без тестов; проверка через spec self-review + регрессию (Pest/Vitest
не затрагиваются — хук вне test-suite приложения).

## 10. Вне scope

- Правка глобального `~/.claude/hooks/economy-mode.py` для упоминания §14 в immunity-строке —
  опциональный follow-up, не блокирует D1/D2.
- Реальная декомпозиция конкретных задач между spawned-агентами — это runtime-поведение,
  не часть этого правила.
- Изменение daemon / hive-mind конфигурации — не затрагивается.
- Толерантность к опечаткам триггера — не реализуется (риск ложных
  срабатываний); матчим корректное написание `queen`/`королева`.

## 11. Затрагиваемые файлы

**Создать:**

- `tools/ruflo-queen-hook.mjs` — хук.
- `tools/ruflo-queen-hook.test.mjs` — тесты.

**Изменить:**

- `.claude/settings.json` — +элемент в `hooks.UserPromptSubmit`.
- `docs/Pravila_raboty_Claude_v1_1.md` — новый §14, §13.6 таблица, §0 note, шапка + §10.
- `CLAUDE.md` — §1, §3.5, шапка (через `claude-md-management` или plan-exception).
- `docs/Plugin_stack_rules_v1.md` — точечный cross-ref + version bump.
- `docs/Tooling_v8_3.md` — §4.10 +queen-триггер + version bump.
- `cspell-words.txt` — при необходимости (англ. «queen» и др.).
- memory: `project_ruflo_integration.md`, `project_state.md`, `MEMORY.md` — фиксация правила.
