🧭 dd-flow (MVP)

dd-flow — локальный флоу-оркестратор для автоматизации AI‑KOD Mini протокола через Codex (TypeScript SDK).

🎯 Что делает

- 🧾 Создаёт .protocols/NNNN-/ и просит агента сгенерировать plan-mini.md.
- 🧩 Компилирует plan-mini.md в compiled-plan.json (Plan IR) и строит action-plan.json (набор действий оркестратора).
- 🛠️ Выполняет шаги плана как последовательность Actions (step/checkpoint/verify/fix/commit) по режиму движка (см. ниже).
- ✅ Делает verification (semantic review) шагов в режиме read-only (без запуска команд) как AgentCheck.
- 🧯 Если checks/verification требуют исправлений — запускает fix-flow (fix agent), затем сохраняет “handoff_for_main” в main session.

🧩 Engine modes

$3

- Каждый шаг: exec → checks → fix-loop (до зелёного) → commit.
- Полезно, когда важно “main всегда зелёный”.

$3

- Шаги выполняются парами: (1,2), (3,4), ...
- Внутри пары: step X exec → commit, затем step X+1 exec → commit
- Затем чекпойнт на HEAD после X+1:
- запускается union(checks[X], checks[X+1]) с dedup по строке команды,
- затем verification (read-only, hard-gate),
- если красное/есть замечания → fix-loop на HEAD до зелёного,
- только после зелёного чекпойнта идём к следующей паре.

$3

- Verification выполняется на чекпойнтах и не запускает команды (dd-flow инлайнит контекст в промпт).
- Сейчас verification трактуется как ещё одна “проверка” внутри чекпойнта (hard-gate): checks → verify → fix → recheck → re-verify.

🗺️ Plan review (планирование и замечания)

dd-flow сохраняет контекст обсуждения в main session, но делает планирование детерминированным через plan-mini.md и compiled-plan.json.

Plan review теперь живёт в главном TUI (pi‑tui) внутри экрана Protocol Feed.
Пользователь видит ленту карточек действий (ledger) и может открыть details‑панель с plan-mini.md / agent logs.

Важный инвариант: до принятия плана dd-flow не делает git commit — коммит плана является итогом процесса планирования (после “Plan review: accepted”).

Во время Plan review доступны действия (через hotkeys в footer):
- ✅ Принять план: dd-flow делает commit .protocols//... и переводит протокол в “ready to execute”.
- 📝 Remarks + rebuild: встроенный remarks‑editor (home SoT) → sync plan-mini.md по чату+remarks → compile.
- 💬 Обсудить план с агентом: dd-flow показывает/копирует команду codex resume и умеет открыть терминал (iterm2/Terminal.app).
- ⏸️ Pause: остановиться на plan review и вернуться позже.

$3

Remarks — технический SoT (home): ~/.dd-flow/projects//protocols/P-/workspace/remarks/plan.md.

В главном TUI remarks редактируются во встроенном modal‑editor (без $EDITOR).

🗂️ Хранилище и артефакты

- 🧰 Home dir dd-flow: ~/.dd-flow/ (можно переопределить через DD_FLOW_ROOT)
- DD_FLOW_ROOT=/tmp/dd-flow-test удобно для e2e/локальных экспериментов: весь SoT окажется в одной папке, без влияния на “боевой” ~/.dd-flow.
- 🧩 Шаблоны промптов (repo-owned): apps/dd-flow/prompts/*/.md (Handlebars {{VARS}})
- По умолчанию dd-flow читает промпты из своей папки prompts/ внутри пакета.
- При желании можно переопределить paths.promptsDir через DD_FLOW_ROOT/config.yaml.
- 🧾 Runs / логи: ~/.dd-flow/runs//...
- logs/timings.jsonl — JSONL‑тайминги ключевых блоков (stages/steps/checks/verify/agent/total).
- 🧠 Protocol runtime (source of truth): ~/.dd-flow/projects//protocols/P-/...
- state.json — SoT состояния протокола (cursor/progress/baseCommit)
- timing.execution.totalActiveMs и timing.actions[] — накопленное “активное” время по протоколу и по action
- compiled-plan.json — скомпилированный план (Plan IR)
- action-plan.json — план действий оркестратора (Actions)
- protocol-ledger.jsonl — append-only события (debug/observability)
- workspace/ACT-XXXX/... — артефакты действий (prompts, reports, logs)
- 📝 Plan remarks (SoT): ~/.dd-flow/projects//protocols/P-/workspace/remarks/plan.md
- редактирование через $EDITOR (по умолчанию nano, fallback vi), плюс inline fallback.
- 🧾 Репозиторий: .protocols//... — человеко‑читабельный слой (plan/context/log/research) и попадает в git‑историю.
- 🧠 Codex sessions:
- основная сессия (main) — dd-flow
- fix agent создаёт отдельную сессию; при ручном вмешательстве dd-flow даёт команду codex resume

🧩 ArtifactSets (concept)

dd-flow трактует качество и контекст как артефакты, которые нужно довести до целевого состояния (converge loop):

- ✅ checkpoint_gates: process checks + verify (hard) + общий fix-loop до зелёного.
- 🔎 step_research: fork‑sessions для исследовательских артефактов → validate → копирование в .protocols/.../research/ до step_exec.

🧷 baseCommit (future hook)

dd-flow сохраняет baseCommit.originMain (SHA origin/main на момент старта протокола). Это заготовка под Full‑протокол:
- Full можно стартовать от последнего стабильного origin/main, даже если в рабочей ветке в данный момент идёт mini/merge.

Также в home создаётся директория ~/.dd-flow/projects//merge-queue/ как заготовка под будущую очередь merge’ей (в MVP не используется).

🧩 Команды

$3

``bash
dd-flow
dd-flow
`

$3

`bash
dd-flow run [--allow-push] [--checks-mode sync|async] [--verify-mode sync|async] [--concurrency N] [--terminal iterm2|terminalapp]
`

Флаги:
- --allow-push: разрешить git push origin main (по умолчанию false)
- --checks-mode: sync или async (дефолт: async)
- --verify-mode: sync или async (дефолт: async)
- --concurrency: параллелизм checks (по умолчанию берётся из DD_FLOW_ROOT/config.yaml, дефолт 5)
- --terminal: адаптер терминала для manual fix (iterm2 по умолчанию)

$3

`bash
dd-flow codex-ping
`

$3

`bash
dd-flow verify-demo --commit HEAD
`

🧯 Manual intervention UX

Если fix не удаётся после auto-retry, dd-flow показывает STOP-меню:
1) открыть терминал и запустить команду вида cd && codex resume
2) 📋 скопировать команду в буфер обмена
3) ✍️ сделать ещё один retry фикса с сообщением пользователя (в той же fix-session)
4) остановить dd-flow

⚠️ Ограничения MVP

- Ожидается запуск из корня проекта (git repo).
- Mini flow ориентирован на ветку main.
- Таймауты checks настраиваются через DD_FLOW_ROOT/config.yaml (idle/max).
- Имя задачи (task_name) должно быть валидным kebab-case (ASCII, длина ограничена); при невалидном ответе naming-агента dd-flow делает retry и может применить безопасный fallback.
- Оркестратор не делает pnpm install (bootstrap — detect-only). Если проверки требуют окружения — это решается через fix-loop (agent + повтор checks).

💡 Примечание про manual fix

Если dd-flow предлагает ручной фикс, запускай именно команду dd-flow (она включает cd && ...), чтобы правки точно попали в основной worktree проекта.

⏱️ Таймаут агента (adaptive)

По умолчанию один turn агента имеет:
- base timeout: 3m
- auto-extend: +2m каждый раз, когда от агента приходят streamed события (progress), пока он “живой”.

Перекрытие через env vars:
- DDFLOW_AGENT_TIMEOUT_MS — base timeout в миллисекундах (например 180000).
- DDFLOW_AGENT_EXTEND_MS — размер авто‑продления в миллисекундах (например 60000).

🧱 Server/CLI split (future)

Сейчас dd-flow — один процесс: engine + UI.

Цель следующего этапа (Full протокол и параллельные линии) — вынести engine в локальный server:
- server: state machine + TaskManager + resource locking + ledger,
- cli: UI/интерактив (prompts/spinners/menus) + thin client.

🧪 Тесты и фейковые провайдеры

Скрипты (root package.json):

`bash
pnpm test:dd-flow
pnpm test:dd-flow:unit
pnpm test:dd-flow:e2e
`

Полезные “fixtures” для тестов (Source of Truth — внутри репозитория):
- apps/dd-flow/src/testing/fixtureAgent.ts — FixtureAgentProvider (LLM/Codex заглушка) + Codex‑like артефакты (prompt.md, stream.jsonl, stream.md, response.json, …).
- apps/dd-flow/src/testing/fixtureGit.ts — FixtureGitClient` (Git заглушка для unit/integration тестов).