@nitra/cursor 4.1.1 → 5.0.0

package/scripts/dispatcher/lib/docs/plan-panel.md

@@ -1,181 +0,0 @@
-# plan-panel.mjs
-
-## Огляд
-
-Модуль `plan-panel.mjs` реалізує **agent↔agent brainstorm** — багатоперсональну панель субагентів, які формують спільну відповідь на задачу. Концептуально це поєднання двох підходів:
-
-- **bmad party-mode** — кілька «персон» одночасно дивляться на проблему з різних кутів;
-- **superpowers dispatching** — окремий суддя-субагент синтезує думки персон в єдину фінальну відповідь.
-
-Панель є спільним механізмом для двох фаз життєвого циклу задачі:
-
-- `mode: 'spec'` — генерує 2–3 текстові підходи до розв’язання у форматі Markdown (для фази специфікації);
-- `mode: 'plan'` — генерує покроковий JSON-план (для фази планування).
-
-Модуль повторно використовує **runner-інтерфейс Фасада B**, який очікує об’єкт із методом `runStep(prompt, opts) => { ok, output }` (контракт, аналогічний `planner.mjs` і `active.mjs` у тому ж каталозі).
-
-Принципово важлива поведінкова характеристика — **HITL (human-in-the-loop)**: панель тільки **повертає синтез** і ніколи не зберігає артефакт самостійно. Апрув людини та фіксація результату належать до контракту `flow.mdc` і виконуються окремими командами (`flow spec` / `flow plan`).
-
-## Експорти / API
-
-Модуль має один публічний експорт:
-
-- `runPanel(input)` — асинхронна функція, що проводить панель і повертає синтез або `null` у разі провалу.
-
-Внутрішні артефакти модуля (не експортуються):
-
-- константа `PERSONAS` — список персон панелі;
-- функція `judgePrompt(mode, proposals, task)` — формує промпт для судді залежно від режиму.
-
-## Функції
-
-### `runPanel({ task, cwd, runner, log, mode })`
-
-**Сигнатура:**
-
-```
-async function runPanel({
-  task,        // string — опис задачі для персон і судді
-  cwd,         // string — робочий каталог, передається в runner.runStep як opts.cwd
-  runner,      // { runStep: (prompt, opts?) => { ok, output } | Promise<{ ok, output }> }
-  log,         // (msg: string) => void — логер помилок; за замовчуванням console.error
-  mode         // 'spec' | 'plan' — режим синтезу; за замовчуванням 'plan'
-}) => Promise<
-  | { task: string, acceptance?: string }[]   // коли mode === 'plan' і JSON парситься
-  | string                                    // коли mode === 'spec'
-  | null                                      // у разі будь-якого фейлу
->
-```
-
-**Параметри:**
-
-- `task` — текстовий опис задачі. Підставляється в системний промпт кожної персони (`<sys>\n\nЗадача: <task>`) та в промпт судді (рядок `Задача: <task>` у кінці).
-- `cwd` — робоча директорія; модуль не використовує її напряму, лише передає у `runner.runStep` через `{ cwd }`.
-- `runner` — обов’язкова ін’єкція з методом `runStep`. Якщо відсутній, функція логуює повідомлення `panel: нема runner — режим --panel недоступний` і повертає `null`.
-- `log` — функція логування непомилкового рівня (фактично використовується тільки для діагностичних повідомлень про помилки). За замовчуванням — `console.error`.
-- `mode` — `'spec'` або `'plan'`. За замовчуванням `'plan'`. Впливає на:
-  - інструкцію в `judgePrompt`;
-  - формат повернення (текст або розпарсений JSON-масив).
-
-**Повертає:**
-
-- Для `mode === 'plan'`: масив об’єктів `{ task: string, acceptance?: string }` після успішного `JSON.parse` фрагмента між першим `[` і останнім `]` у відповіді судді.
-- Для `mode === 'spec'`: рядок `judge.output` (Markdown від судді) як є.
-- `null` — у будь-якому з провальних сценаріїв (див. далі).
-
-**Сценарії повернення `null`:**
-
-1. Не передано `runner` → лог `panel: нема runner — режим --panel недоступний`.
-2. Виклик судді завершився `{ ok: false }` → лог `panel: суддя-синтез завершився помилкою`.
-3. Режим `plan`, але у виводі судді не знайдено JSON-меж (`[` / `]`) або `end < start` → лог `panel: суддя не повернув JSON-план`.
-4. Режим `plan`, JSON знайдено, але `JSON.parse` кинув виняток → лог `panel: невалідний JSON синтезу`. Виняток ловиться `catch {}` і не пробрасується далі.
-
-**Алгоритм (по кроках):**
-
-1. Перевірити наявність `runner`; якщо нема — залогувати й вийти з `null`.
-2. Паралельно через `Promise.all` опитати всі персони з `PERSONAS`:
-   - для кожної персони викликати `runner.runStep(<sys>\n\nЗадача: <task>, { cwd })`;
-   - сформувати рядок `### <name>\n<output або "(порожньо)" якщо !ok>`.
-3. Склеїти всі думки персон через `\n\n` і викликати суддю промптом, побудованим у `judgePrompt(mode, proposals, task)`.
-4. Якщо суддя `!ok` — лог і `null`.
-5. Якщо `mode === 'spec'` — повернути `judge.output` без обробки.
-6. Інакше (plan): знайти межі JSON-масиву (`indexOf('[')` та `lastIndexOf(']')`), валідувати їх; розпарсити `slice(start, end + 1)` і повернути; у разі помилки парсингу — лог і `null`.
-
-**Side effects:**
-
-- **Зовнішні виклики моделей через `runner.runStep`**: персон — `PERSONAS.length` (зараз 3), плюс один виклик судді. Усього 4 запити на один прогін `runPanel`.
-- **Логування**: виключно через переданий `log` (за замовчуванням `console.error`). Інших звернень до stdout/stderr нема.
-- **Файлову систему не чіпає**, мережу безпосередньо не використовує (опосередковано — через `runner`), артефактів не зберігає (HITL — фіксацію робить агент за `flow.mdc`).
-- **Конкурентність**: запити персон виконуються паралельно (`Promise.all` + `map(async …)`); виклик судді — послідовно після завершення всіх персон.
-
-### `judgePrompt(mode, proposals, task)`
-
-**Сигнатура:**
-
-```
-function judgePrompt(
-  mode: 'spec' | 'plan',
-  proposals: string,
-  task: string
-): string
-```
-
-**Параметри:**
-
-- `mode` — режим синтезу. Визначає інструкцію в «голові» промпту:
-  - `'plan'` — три рядки інструкції: вимога ОДНОГО покрокового плану, обмеження ≤ 5 хв на крок із критерієм приймання, вимога повернути **ЛИШЕ JSON-масив без коментарів** у форматі `[{ "task": "...", "acceptance": "..." }, ...]`.
-  - `'spec'` (та будь-яке інше значення) — дві інструкції: 2–3 підходи з рекомендацією й коротким дизайном, повернути людино-читабельний Markdown.
-- `proposals` — попередньо склеєні думки персон (зазвичай `proposals.join('\n\n')` із масиву `### name\noutput`).
-- `task` — оригінальний опис задачі (рядок `Задача: <task>` додається в кінець промпту).
-
-**Повертає:** рядок промпту, склеєний через `\n` у вигляді:
-
-```
-<head-line-1>
-<head-line-2>
-[<head-line-3 — лише для plan>]
-
-<proposals>
-
-Задача: <task>
-```
-
-**Side effects:** чиста функція без побічних ефектів і зовнішніх викликів.
-
-## Залежності
-
-### Зовнішні модулі / пакети
-
-- **Жодних `import`** із Node.js core, npm-пакетів чи інших файлів проєкту. Модуль повністю самодостатній.
-
-### Глобали
-
-- `console.error` — використовується як **дефолтне** значення параметра `log`. Якщо викликач передасть власний `log`, `console` не використовується.
-- `Promise`, `JSON`, `Array.isArray` (не використовується), `String.prototype.indexOf` / `lastIndexOf` / `slice` — стандартні JS-примітиви.
-
-### Контрактні (поведінкові) залежності
-
-- **Runner-інтерфейс Фасада B**: `runner.runStep(prompt: string, opts?: { cwd: string }) => { ok: boolean, output: string } | Promise<{ ok, output }>`. Цей контракт реалізують сусідні модулі — наприклад, `planner.mjs` і `active.mjs` у каталозі `lib/`.
-- **HITL за `flow.mdc`**: правила Flow вимагають, щоб фіксацію артефакту (`flow spec` / `flow plan`) виконував агент окремою командою; панель сама артефактів не пише.
-
-### Внутрішні константи
-
-- `PERSONAS` — масив із трьох записів `[name, systemPrompt]`:
-  - `architect` — «Запропонуй найчистішу архітектуру розв’язання. Стисло, по суті.»
-  - `skeptic` — «Назви ризики, граничні випадки і що може піти не так. Стисло.»
-  - `tester` — «Опиши, які тести доведуть коректність. Стисло.»
-
-## Потік виконання / Використання
-
-### Типовий потік виклику
-
-1. Викликач (наприклад, CLI-команда фази `spec` чи `plan`) отримує `runner`, що інкапсулює запуск субагента (модель + транспорт), і поточний `cwd`.
-2. Викликач формулює `task` і обирає `mode` (`'spec'` або `'plan'`).
-3. Викликає `await runPanel({ task, cwd, runner, mode, log? })`.
-4. Внутрішньо панель:
-   - паралельно опитує `architect`, `skeptic`, `tester` — кожна повертає текстову думку (`### <name>\n<output>` або `(порожньо)` у разі `!ok`);
-   - формує промпт судді через `judgePrompt`, який отримує всі думки + оригінальне завдання;
-   - запускає суддю одним викликом `runner.runStep`;
-   - на основі `mode` повертає або сирий Markdown (`spec`), або розпарсений JSON-масив кроків (`plan`).
-5. Викликач отримує результат і:
-   - для `null` — повідомляє користувача та припиняє/повторює фазу;
-   - для `spec` (рядок) — показує користувачу й чекає `flow spec` для фіксації;
-   - для `plan` (масив кроків) — передає далі (виконавцю/планеру) і чекає `flow plan` для фіксації.
-
-### Очікувані формати виводу судді
-
-- **`plan`**: модель повинна повернути рядок, у якому міститься JSON-масив об’єктів вигляду `{ "task": "...", "acceptance": "..." }`. Парсер толерантний до «обгортки» (текст до першого `[` і після останнього `]` ігнорується), але самий JSON має бути валідним.
-- **`spec`**: довільний Markdown-текст; жодних обмежень формату на стороні модуля.
-
-### Гарантії та обмеження
-
-- **Ніколи не кидає виняток назовні**: усі провальні шляхи завершуються `null` + лог через `log()`. `try/catch` навколо `JSON.parse` ловить навіть synthax-помилки парсингу.
-- **Паралелізм персон**: усі персони запускаються одночасно — це впливає на навантаження `runner` (зараз 3 паралельні виклики моделі) та сумарну затримку (≈ max(persona-latency) + judge-latency, а не сума).
-- **Не зберігає стан** між викликами; кожен виклик `runPanel` повністю самодостатній.
-- **Не валідує внутрішню структуру** елементів JSON-плану — тип `{ task: string, acceptance?: string }[]` зазначений у JSDoc, але рантайм-перевірки полів немає. Викликач відповідає за подальшу валідацію.
-
-### Розширюваність
-
-- Додати персону: дописати запис у масив `PERSONAS`. Жодних інших змін не потрібно — обхід йде через `map`.
-- Додати режим: розширити умову в `judgePrompt` (та, за потреби, гілку обробки виводу у `runPanel`).
-- Підмінити модель/транспорт: реалізувати інший `runner` із тим самим контрактом `runStep` — модуль працює з будь-яким об’єктом, що задовольняє інтерфейс.

package/scripts/dispatcher/lib/docs/plan.md

@@ -1,200 +0,0 @@
-# plan.mjs — фаза `plan` команди `flow`
-
-## Огляд
-
-Модуль `plan.mjs` реалізує фазу **плану** lifecycle-команди `flow` (модель «Пасивний Турнікет», §4 правила `n-flow`). Це чистий «turnstile»-крок: він **не пише кодові артефакти** — лише фіксує план роботи у persistent-стані `.flow.json` поточного worktree та супутньому event-log.
-
-Команда CLI:
-
-```
-flow plan [--panel] [<plan.md>]
-```
-
-Високорівнева семантика:
-
-1. Резолвить активний `flow`-state (`.flow.json`) у поточному `cwd` або за параметром `branch`.
-2. Перевіряє, що state існує (`flow init` був запущений раніше). Якщо ще не зафіксована spec — попереджає, але не блокує.
-3. Бере **кроки плану** одним із двох способів (brainstorm-моделей з `flow.mdc`):
-   - **human↔agent** — читає `docs/plans/<date>-<slug>.md` (передано аргументом або резолвиться по бренчу) і витягує `## Кроки` як список steps.
-   - **agent↔agent (`--panel`)** — викликає `runPanel` (панель персон + суддя) через subagent-runner і отримує синтезовані кроки.
-4. Нормалізує steps через `parsePlan` (валідація формату/структури → масив об'єктів кроків).
-5. Read-only `verifyTrace` перевіряє цілісність ланцюга `spec → plan → flow` (front-matter лінки). При розриві лише попереджає у лог (не падає).
-6. Записує transition у state-store: `plan` ← `normalized`, `plan_doc` ← шлях до md (або `null` для panel-режиму), `status` ← `'planned'`. Тип події — `plan`, payload — `{ steps: <кількість> }`.
-7. Логує підсумок і повертає `0`.
-
-Будь-яка помилка (відсутність state, відсутність плану-доку, невалідний формат, неможливість підняти runner) логується через `log` і повертає `1`.
-
-## Експорти / API
-
-| Експорт             | Тип              | Призначення                                                |
-| ------------------- | ---------------- | ---------------------------------------------------------- |
-| `plan(rest, deps?)` | `async function` | Виконати фазу `plan` поточного `flow`. Іменований експорт. |
-
-Інших експортів немає (немає `default`).
-
-### Сигнатура
-
-```js
-export async function plan(rest, deps = {}) → Promise<number>
-```
-
-### Параметри
-
-- `rest: string[]` — позиційні аргументи CLI (після `plan`). Розпізнаються:
-  - `--panel` — увімкнути agent↔agent режим (панель персон).
-  - перший елемент із суфіксом `.md` — явний шлях до plan-доку (інакше резолвиться через `resolveArtifact(cwd, 'plans', state.branch)`).
-- `deps?: object` — bag залежностей для ін'єкції в тестах:
-  - `cwd?: string` — стартовий `cwd` (default: `process.cwd()`).
-  - `branch?: string` — підказка про активний flow для авторезолву поза worktree.
-  - `log?: (msg: string) => void` — sink для повідомлень (default: `console.error`).
-  - `runner?: object` — готовий subagent-runner (для `--panel`). Якщо немає — створюється через `createRunner(deps)`.
-  - `trace?: (cwd: string) => number` — кастомна імплементація trace-перевірки для `verifyTrace`.
-  - `now?: () => number` — джерело часу для transition-таймстампу (default: `Date.now`).
-
-### Повертає
-
-`Promise<number>` — exit code:
-
-- `0` — план зафіксовано, state переведено у `planned`.
-- `1` — будь-яка помилка: нема state-файлу/active flow, нема plan-доку у режимі без `--panel`, runner не піднявся, `parsePlan` упав на валідації, panel повернув пустий результат.
-
-### Side effects
-
-- Читає файлову систему: `.flow.json` (через `readState`), доки плану через `readFileSync`, `existsSync`.
-- Пише через `recordTransition`: оновлює `.flow.json` та аппендить запис у `flowEventsPath(cwd)`.
-- Викликає `log(...)` (за замовчуванням — `console.error`).
-- У режимі `--panel` запускає підпроцес/subagent-runner через `createRunner` (мережа/LLM-виклики залежно від реалізації runner).
-
-## Функції
-
-У файлі **одна** експортована функція `plan` — описана вище. Внутрішніх допоміжних функцій немає.
-
-### `plan(rest, deps)` — деталі потоку
-
-**Сигнатура:** `(rest: string[], deps?: PlanDeps) → Promise<number>`
-
-**Послідовність:**
-
-1. **Резолв cwd і логера** — `cwd0 = deps.cwd ?? processCwd()`, `log = deps.log ?? console.error`.
-2. **Резолв активного flow** — `resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)`.
-   - Якщо `resolved.statePath` пустий — log `plan: <error>` і `return 1`.
-   - Якщо `resolved.autoResolved === true` — log повідомлення про авторезолв (cwd поза worktree).
-   - `cwd` для подальших операцій = `resolved.worktreeDir ?? cwd0`.
-3. **Читання state** — `readState(statePath)`; якщо `null` → `'plan: стану нема — спершу `flow init`'` і `return 1`.
-4. **Soft-гейт по spec** — якщо `state.status !== 'spec'` і `!state.spec_doc` — лише попередження (`'plan: дизайн ще не зафіксовано — рекомендовано спершу `flow spec` (не блокує)'`), виконання продовжується.
-5. **Резолв plan-доку** — `doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'plans', state.branch)`.
-6. **Збір steps**:
-   - **Гілка `--panel`:**
-     - Якщо `deps.runner` не передано — пробує `createRunner(deps)`, на throw → log і `return 1`.
-     - `steps = await runPanel({ task: state.branch, cwd, runner, log, mode: 'plan' })`.
-     - Якщо `steps` falsy → `return 1` (panel вирішив не комітити).
-   - **Гілка з документом:**
-     - Якщо `!doc || !existsSync(doc)` → log `'plan: нема docs/plans/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)'` і `return 1`.
-     - `steps = extractSteps(readFileSync(doc, 'utf8'))`.
-7. **Нормалізація** — `parsePlan(JSON.stringify(steps))` у try/catch; помилка → log і `return 1`. Результат — `normalized` (масив крокових об'єктів).
-8. **Trace-перевірка** — `verifyTrace(cwd, deps.trace)`; якщо `false` — лише warning з пр **U+26A0**: `'⚠️ plan: trace виявив розрив ланцюга — перевір лінки spec/plan/flow'`.
-9. **Transition** — `recordTransition`:
-   - target: `{ statePath, eventsPath: flowEventsPath(cwd) }`.
-   - event: `{ type: 'plan', steps: normalized.length }`.
-   - reducer: `s => ({ ...s, plan: normalized, plan_doc: doc ?? null, status: 'planned' })`.
-   - clock: `deps.now ?? Date.now`.
-10. **Лог підсумку** — `'plan: зафіксовано <N> кроків → status: planned'`, **return 0**.
-
-**Інваріанти:**
-
-- Функція не модифікує state у разі будь-якого `return 1` до кроку 9.
-- `plan_doc` свідомо може бути `null` (panel-режим без файлу).
-- Trace-розрив **не блокує** запис — це м'який сигнал розробнику.
-
-## Залежності
-
-### Зовнішні (node:)
-
-- `node:fs` — `existsSync`, `readFileSync` (читання plan-доку).
-- `node:process` — `cwd as processCwd` (default-резолв робочої директорії).
-
-### Внутрішні модулі lib/
-
-- `./artifact.mjs` — `extractSteps` (парс `## Кроки` з md), `resolveArtifact` (резолв `docs/<kind>/<date>-<slug>.md` за бренчем), `verifyTrace` (read-only валідація ланцюга front-matter).
-- `./events.mjs` — `flowEventsPath` (шлях до event-log поточного flow).
-- `./planner.mjs` — `parsePlan` (нормалізація+валідація steps).
-- `./plan-panel.mjs` — `runPanel` (agent↔agent режим, mode: `'plan'`).
-- `./subagent-runner.mjs` — `createRunner` (фабрика runner-а для LLM-викликів у panel).
-- `./state-store.mjs` — `readState` (читання `.flow.json`), `recordTransition` (атомарне оновлення стану + event).
-- `./flow-resolve.mjs` — `resolveActiveFlowState` (резолв активного flow зі `cwd`/`branch`, авторезолв за межами worktree).
-
-Жодних transitive npm-пакетів напряму звідси не використовується.
-
-## Потік виконання / Використання
-
-### Як цей модуль використовується
-
-Файл є **обробником субкоманди** dispatcher-а команди `flow`. Очікувано викликається з вищого рівня (CLI-entry, наприклад `npm/scripts/dispatcher/cli.mjs` чи аналогічного), куди передаються розпарсені аргументи. Виклик можна представити так:
-
-```js
-import { plan } from './lib/plan.mjs'
-
-const code = await plan(process.argv.slice(3))
-process.exit(code)
-```
-
-### Сценарії використання
-
-1. **Human↔agent (типовий ручний flow)**
-
-   ```
-   flow init my-feature        # створив .flow.json
-   flow spec                   # зафіксував docs/specs/<...>.md
-   # brainstorm у Cursor/Claude → з'явився docs/plans/<date>-my-feature.md з '## Кроки'
-   flow plan                   # резолвить plan-doc за branch, фіксує steps, status → planned
-   ```
-
-2. **Agent↔agent (panel)**
-
-   ```
-   flow plan --panel
-   ```
-
-   Без plan-доку: панель персон через `runPanel({ mode: 'plan' })` синтезує `steps`. Записує `plan_doc: null`.
-
-3. **Явний шлях**
-   ```
-   flow plan docs/plans/2026-06-03-my-feature.md
-   ```
-   Перший `*.md`-аргумент у `rest` має пріоритет над `resolveArtifact`.
-
-### Стан до/після
-
-| Поле `.flow.json` | До `plan`                         | Після `plan`                             |
-| ----------------- | --------------------------------- | ---------------------------------------- |
-| `status`          | `'spec'` (рекомендовано) або інше | `'planned'`                              |
-| `plan`            | відсутнє/попереднє                | `normalized` (масив steps)               |
-| `plan_doc`        | відсутнє                          | абсолютний шлях до md або `null` (panel) |
-
-В event-log дописується `{ type: 'plan', steps: <N>, ts: <now> }` (фактичний формат — в `recordTransition`).
-
-### Exit code контракт
-
-- `0` — успіх, можна переходити до наступної фази (`flow code`/`flow review` за конвенцією `n-flow`).
-- `1` — будь-яка помилка; стан **не модифікується**, кроки не записані.
-
-### Обробка помилок
-
-Жодних винятків назовні: усі try/catch перетворені у `log + return 1`. Виключення — баги нижчих рівнів (`recordTransition`, `readState`) — на цьому шарі не загорнуті, тож можуть пропагуватися як unhandled rejection у CLI.
-
-## Rebuild Test
-
-Цього модуля **достатньо** для відтворення з нуля за цією специфікацією за умови наявності таких контрактів-сусідів:
-
-- `resolveActiveFlowState({ cwd, branch }, deps) → { statePath, worktreeDir?, autoResolved?, label?, error? }`.
-- `readState(statePath) → object | null` з принаймні полями `{ branch, status, spec_doc? }`.
-- `resolveArtifact(cwd, kind, branch) → string | undefined` (абсолютний шлях до `docs/<kind>/<date>-<slug>.md`).
-- `extractSteps(mdString) → Array` (парсить `## Кроки`).
-- `parsePlan(jsonString) → Array` (валідація; кидає `Error` з полем `.message`).
-- `runPanel({ task, cwd, runner, log, mode }) → Promise<Array | undefined>`.
-- `createRunner(deps) → Promise<runner>` (може кидати `Error`).
-- `verifyTrace(cwd, traceFn?) → boolean`.
-- `flowEventsPath(cwd) → string`.
-- `recordTransition({ statePath, eventsPath }, event, reducer, now) → void`.
-
-Маючи їх — модуль повністю відновлюється з опису вище: 10 кроків функції `plan`, дві гілки збору `steps`, exit-code-контракт, side-effects через `recordTransition`.