workflow-ai 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+## [1.2.0] — 2026-04-28
+
+### New Features
+- **New built-in stage type: `manual-gate`** — Adds support for manual approval steps in pipelines. When a stage with `type: manual-gate` is encountered, the runner creates a pending approval file in `.workflow/approvals/{step_id}.json` and enters a polling loop, waiting for an external decision (`approved`/`rejected`).
+
+  **Key capabilities:**
+  - Deterministic `step_id` generation: `{ticket_id}_{stageId}_{attempt}` (e.g., `QA-12_manual-approve_0`)
+  - Idempotent file creation — pending file is not overwritten on retry/restart
+  - Configurable polling interval (`poll_interval_ms`, default 2000ms) and optional timeout (`timeout_seconds`)
+  - Graceful handling of SIGTERM/runner stop (returns `aborted`)
+  - Immediate return if file already has `approved`/`rejected` status (crash recovery)
+  - JSON approval file format with full audit trail (`created_at`, `updated_at`, `decided_by`, `comment`, `context_snapshot`)
+
+  **Pipeline configuration example:**
+  ```yaml
+  stages:
+    manual-approve-deploy:
+      type: manual-gate
+      poll_interval_ms: 2000
+      timeout_seconds: 86400
+      goto:
+        approved: continue-deploy
+        rejected: rollback
+        timeout: notify-stuck
+        aborted: end
+  ```
+
+  **Two approval methods (both opt-in):**
+  1. **External MCP/client**: tools like `workflow-mcp` can write to approval files programmatically
+  2. **Direct file edit**: users can simply edit `.workflow/approvals/{step_id}.json` and change `status` to `approved` or `rejected`
+
+  **Important:** `manual-gate` is **opt-in** — pipelines without such stages work identically to previous versions. No breaking changes.
+
+### Changed
+- No breaking changes. All existing pipelines without `manual-gate` stages are fully backward compatible.
+
+### Fixes
+- None
+
+### Technical Notes
+- Approval files are stored in `<project_root>/.workflow/approvals/`
+- Runner validates `manual-gate` stages on startup — requires `goto.approved` and `goto.rejected`, validates numeric parameters
+- New methods added to `PipelineRunner`: `computeStepId()`, `writeApprovalPending()`, `readApprovalFile()`, `executeManualGate()`
+
+### References
+- PLAN-009: workflow-ai 1.2 — manual-gate stage and approval files for workflow-mcp Sprint 2 integration
+- IMPL-55, IMPL-56, IMPL-57, IMPL-58: Implementation tickets
+- QA-35, QA-36, QA-37: Test coverage
+- IMPL-51, QA-55 in workflow-mcp: Dependent consumer work

package/README.md

@@ -102,14 +102,63 @@ workflow run
 20. **analyze-report / decompose-gaps** — проанализировать результаты и итерировать
 21. **complete-plan / increment-plan-iterations** — закрыть план или запустить следующую итерацию
 
-### Поддерживаемые агенты
+### Типы стадий
+
+#### `update-counter`
+Встроенная стадия, инкрементирует счётчик и возвращает статус для перехода. Требует `counter` и опционально `max`. Возвращает `default` или `max_reached`.
+
+#### `manual-gate`
+Встроенная стадия для ручного одобрения. Создаёт файл `.workflow/approvals/{step_id}.json` со статусом `pending` и ждёт решения через polling (интервал по умолчанию 2000мс).
+
+**Параметры:**
+- `poll_interval_ms` — интервал опроса (опц., default 2000)
+- `timeout_seconds` — таймаут в секундах (опц., default без таймаута)
+
+**Требуемые goto:**
+- `approved` — обязательный, переход при одобрении
+- `rejected` — обязательный, переход при отклонении
+
+**Опциональные goto:**
+- `timeout` — при истечении таймаута
+- `aborted` — при остановке runner'а (SIGTERM)
+
+**Формат step_id:** `{ticket_id}_{stageId}_{attempt}` (например, `QA-12_manual-approve_0`)
+
+**Approval-файл содержит:**
+```json
+{
+  "step_id": "QA-12_manual-approve_0",
+  "ticket_id": "QA-12",
+  "stage_id": "manual-approve",
+  "attempt": 0,
+  "status": "pending",
+  "created_at": "2026-04-28T12:34:56.789Z",
+  "updated_at": "2026-04-28T12:34:56.789Z",
+  "decided_by": null,
+  "comment": null,
+  "context_snapshot": { ... }
+}
+```
 
-| Агент | Описание |
-|-------|----------|
-| `claude-code` | Claude Opus — мощная модель для сложных задач |
-| `qwen-code` | Qwen Code — альтернативный агент |
-| `kilo-code` | Kilo Code — мультирежимный агент |
-...
+**Два способа одобрения:**
+1. **Через MCP-клиент** (например `workflow-mcp`): tool `approve_step({step_id, decision, comment})` пишет в файл approval
+2. **Прямая правка файла:** открыть `.workflow/approvals/{step_id}.json`, изменить `"status": "pending"` на `"approved"` или `"rejected"`, сохранить
+
+**Важное:** `manual-gate` — **opt-in**. Если ваш pipeline не использует стадии `manual-gate`, поведение полностью идентично предыдущим версиям! Никаких breaking changes.
+
+**Пример:**
+```yaml
+stages:
+  manual-approve-deploy:
+    type: manual-gate
+    poll_interval_ms: 2000
+    timeout_seconds: 86400
+    goto:
+      approved: continue-deploy
+      rejected: rollback
+      timeout: notify-stuck
+      aborted: end
+```
 
 Агенты настраиваются в `configs/pipeline.yaml`.
 
@@ -343,6 +392,55 @@ agents:
 
 Определение конвейера: агенты, стадии, управление потоком, goto-логика, стратегии повторов.
 
+#### `manual-gate` stage
+
+`type: manual-gate` — встроенный тип стадии для ручного одобрения. Создаёт файл `.workflow/approvals/{step_id}.json` со статусом `pending` и ждёт решения через polling.
+
+**Поля:**
+- `type: manual-gate` — обязательное, идентификатор типа стадии
+- `poll_interval_ms` — опциональное, интервал опроса в мс (default: 2000, минимум: 100)
+- `timeout_seconds` — опциональное, таймаут в секундах (default: null — без таймаута)
+- `goto.approved` — обязательное, следующая стадия при одобрении
+- `goto.rejected` — обязательное, следующая стадия при отклонении
+- `goto.timeout` — опциональное, следующая стадия при истечении таймаута
+- `goto.aborted` — опциональное, следующая стадия при остановке runner'а (SIGTERM)
+
+**Пример:**
+```yaml
+stages:
+  manual-approve-deploy:
+    type: manual-gate
+    poll_interval_ms: 2000
+    timeout_seconds: 86400
+    goto:
+      approved: continue-deploy
+      rejected: rollback
+      timeout: notify-stuck
+      aborted: end
+```
+
+**Два способа одобрения:**
+1. **Через MCP-клиент** (например `workflow-mcp`): tool `approve_step({step_id, decision, comment})` пишет в файл approval. Опционально — пользователю не обязал подключать MCP.
+2. **Прямая правка файла:** открыть `.workflow/approvals/{step_id}.json`, изменить `"status": "pending"` на `"approved"` или `"rejected"`, сохранить. **Базовый способ, работающий без какой-либо внешней инфраструктуры** — достаточно текстового редактора.
+
+**Важное:** `manual-gate` — **opt-in**. Если ваш pipeline не использует стадии `manual-gate`, поведение полностью идентично предыдущим версиям! Никаких breaking changes.
+
+**Формат approval-файла:**
+```json
+{
+  "step_id": "QA-12_manual-approve_0",
+  "ticket_id": "QA-12",
+  "stage_id": "manual-approve",
+  "attempt": 0,
+  "status": "pending",
+  "created_at": "2026-04-28T12:34:56.789Z",
+  "updated_at": "2026-04-28T12:34:56.789Z",
+  "decided_by": null,
+  "comment": null,
+  "context_snapshot": { ... }
+}
+```
+
 ### `configs/ticket-movement-rules.yaml`
 
 Правила автоматического перемещения тикетов на основе статуса ревью.

package/configs/pipeline.yaml

@@ -90,6 +90,20 @@ pipeline:
       capabilities: [text]
       description: "Kilo deepseek"
 
+    deepseek-flash:
+      command: "kilo"
+      args: ["-m", "deepseek/deepseek-v4-flash", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
+      workdir: "."
+      capabilities: [text]
+      description: "Kilo deepseek"
+
+    deepseek-pro:
+      command: "kilo"
+      args: ["-m", "deepseek/deepseek-v4-pro", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
+      workdir: "."
+      capabilities: [text]
+      description: "Kilo deepseek"
+
     kilo-minimax:
       command: "kilo"
       args: ["-m", "kilo/minimax/minimax-m2.7", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
@@ -104,6 +118,13 @@ pipeline:
       capabilities: [text]
       description: "Kilo free"
 
+    openrouter-free:
+      command: "kilo"
+      args: ["-m", "kilo/openrouter/free", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
+      workdir: "."
+      capabilities: [text]
+      description: "Kilo free"
+
     script-move:
       command: "node"
       args: [".workflow/src/scripts/move-ticket.js"]
@@ -576,10 +597,10 @@ pipeline:
       description: "Выполнить выбранную задачу"
       skill: execute-task
       counter: task_attempts
-      agents: [kilo-free, kilo-glm-air, claude-haiku, claude-sonnet, claude-opus, kilo-minimax, kilo-deepseek]
+      agents: [kilo-free, openrouter-free, kilo-glm-air, claude-haiku, claude-sonnet, claude-opus, kilo-minimax, deepseek-flash]
       agents_by_type:
         coach:
-          agents: [kilo-glm, claude-sonnet, kilo-minimax, kilo-deepseek]
+          agents: [kilo-glm, claude-sonnet, deepseek-pro, kilo-minimax]
           instructions: "Твоя роль: coach"
         qa:
           agents: [claude-haiku, kilo-glm, claude-sonnet, claude-opus, kilo-minimax]

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "workflow-ai",
-  "version": "1.1.0",
-  "description": "AI Agent Workflow Coordinator — kanban-based pipeline for AI coding agents",
-  "type": "module",
-  "bin": {
-    "workflow": "./bin/workflow.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/cli.mjs",
-    "src/init.mjs",
-    "src/runner.mjs",
-    "src/wf-loader.mjs",
-    "src/global-dir.mjs",
-    "src/junction-manager.mjs",
-    "src/lib/",
-    "src/scripts/",
-    "src/skills/",
-    "templates/",
-    "configs/",
-    "agent-templates/"
-  ],
-   "exports": {
-     "./lib/find-root.mjs": "./src/lib/find-root.mjs",
-     "./lib/utils.mjs": "./src/lib/utils.mjs",
-     "./lib/logger.mjs": "./src/lib/logger.mjs",
-     "./lib/js-yaml.mjs": "./src/lib/js-yaml.mjs",
-     "./lib/operations/tickets.mjs": "./src/lib/operations/tickets.mjs",
-     "./lib/operations/plans.mjs": "./src/lib/operations/plans.mjs",
-     "./lib/operations/skills.mjs": "./src/lib/operations/skills.mjs"
-   },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "test": "node --test src/tests/*.test.mjs",
-    "test:skills": "node src/scripts/run-skill-tests.js --all",
-    "release": "npm version patch && npm publish"
-  },
-  "dependencies": {
-    "js-yaml": "^4.1.0"
-  }
-}
+{
+  "name": "workflow-ai",
+  "version": "1.2.1",
+  "description": "AI Agent Workflow Coordinator — kanban-based pipeline for AI coding agents",
+  "type": "module",
+  "bin": {
+    "workflow": "./bin/workflow.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/cli.mjs",
+    "src/init.mjs",
+    "src/runner.mjs",
+    "src/wf-loader.mjs",
+    "src/global-dir.mjs",
+    "src/junction-manager.mjs",
+    "src/lib/",
+    "src/scripts/*.js",
+    "src/skills/*/SKILL.md",
+    "src/skills/*/index.mjs",
+    "templates/",
+    "configs/",
+    "agent-templates/",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./lib/find-root.mjs": "./src/lib/find-root.mjs",
+    "./lib/utils.mjs": "./src/lib/utils.mjs",
+    "./lib/logger.mjs": "./src/lib/logger.mjs",
+    "./lib/js-yaml.mjs": "./src/lib/js-yaml.mjs",
+    "./lib/operations/tickets.mjs": "./src/lib/operations/tickets.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/tests/*.test.mjs",
+    "test:skills": "node src/scripts/run-skill-tests.js --all",
+    "release": "npm version patch && npm publish"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}