🧭 dd-flow (MVP)

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

🎯 Что делает

• 🧾 Создаёт .protocols/NNNN-<task>/ и просит агента сгенерировать 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

✅ checks-sync (строгий режим)

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

🚀 checks-async (дефолт, чекпойнты по парам)

• Шаги выполняются парами: (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 до зелёного,
  • только после зелёного чекпойнта идём к следующей паре.

🔍 Verify mode

• 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/<NNNN-task>/... и переводит протокол в “ready to execute”.
• 📝 Remarks + rebuild: встроенный remarks‑editor (home SoT) → sync plan-mini.md по чату+remarks → compile.
• 💬 Обсудить план с агентом: dd-flow показывает/копирует команду codex resume <mainSessionId> и умеет открыть терминал (iterm2/Terminal.app).
• ⏸️ Pause: остановиться на plan review и вернуться позже.

📝 Remarks editor

Remarks — технический SoT (home): ~/.dd-flow/projects/<projectId>/protocols/P-<NNNN>/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/config.json.
• 🧾 Runs / логи: ~/.dd-flow/runs/<runId>/...
  • logs/timings.jsonl — JSONL‑тайминги ключевых блоков (stages/steps/checks/verify/agent/total).
• 🧠 Protocol runtime (source of truth): ~/.dd-flow/projects/<projectId>/protocols/P-<NNNN>/...
  • state.json — SoT состояния протокола (cursor/progress/baseCommit)
    • timing.execution.totalActiveMs и timing.actions[<actionId>] — накопленное “активное” время по протоколу и по 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/<projectId>/protocols/P-<NNNN>/workspace/remarks/plan.md
  • редактирование через $EDITOR (по умолчанию nano, fallback vi), плюс inline fallback.
• 🧾 Репозиторий: .protocols/<NNNN-task>/... — человеко‑читабельный слой (plan/context/log/research) и попадает в git‑историю.
• 🧠 Codex sessions:
  • основная сессия (main) — dd-flow <session-id>
  • fix agent создаёт отдельную сессию; при ручном вмешательстве dd-flow даёт команду codex resume <fixSessionId>

🧩 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/<projectId>/merge-queue/ как заготовка под будущую очередь merge’ей (в MVP не используется).

🧩 Команды

🧭 Главный TUI (picker / protocol feed)

dd-flow
dd-flow <NNNN|protocol-name|session-id>

🚀 Запуск mini orchestrator

dd-flow run <session-id|NNNN> [--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/config.json, дефолт 5)
• --terminal: адаптер терминала для manual fix (iterm2 по умолчанию)

🧪 Быстрая проверка, что resume работает

dd-flow codex-ping <session-id>

🔬 Demo: verification pipeline

dd-flow verify-demo <session-id> --commit HEAD

🧯 Manual intervention UX

Если fix не удаётся после auto-retry, dd-flow показывает STOP-меню:

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

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

• Ожидается запуск из корня проекта (git repo).
• Mini flow ориентирован на ветку main.
• Таймауты checks настраиваются через ~/.dd-flow/config.json (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 <PROJECT_ROOT> && ...), чтобы правки точно попали в основной 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):

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, events.jsonl, response.json, …).
• apps/dd-flow/src/testing/fixtureGit.ts — FixtureGitClient (Git заглушка для unit/integration тестов).