workflow-ai 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,61 +1,61 @@
-## [1.3.0] — 2026-04-30
-
-### Добавлено
-- **Новый тип стейджа: `mark-blocked` и расширение frontmatter** — Добавлены поля `auto_blocked_reason`, `auto_blocked_attempts`, `auto_blocked_at` для автоматического отслеживания причин и попыток блокировки тикетов. Стейдж `mark-blocked` позволяет устанавливать эти поля в зависимости от условий бизнес-логики.
-- **Новый тип стейджа: `manual-gate-human`** — Добавлен статус `human_ready` в `pick-next-task.js`. При достижении этого статуса задача ожидает ручного решения оператора перед продолжением выполнения.
-- **Хук одобрения в `move-ticket.js`** — Добавлен approval-hook, проверяющий наличие ожидающих решения одобрений перед перемещением тикета в терминальные состояния.
-- **Расширение START-лога полем `ticket="X"`** — Добавлено поле с идентификатором тикета в стартовый лог для улучшенной трассировки и связывания логов с конкретными задачами.
-- **Исправление `approval-pending.mjs` (поле `created_at`)** — Исправлено некорректное заполнение поля `created_at` при создании файлов ожидающих решения.
-
-> **Примечание:** версия 1.2.0 не была опубликована в npm. При выполнении `npm publish`
-> сработал prepublishOnly/postversion скрипт, автоматически поднявший версию до 1.2.1.
-> Git-тег `v1.2.0` (коммит 179d52b) соответствует состоянию до publish; `v1.2.1` (коммит 83d1b70) —
-> фактически опубликованной версии.
-
-### 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
-- Исправлено сохранение временной метки `created_at` в файлах одобрений (approval-pending.mjs)
-
-### 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
+## [1.3.0] — 2026-04-30
+
+### Добавлено
+- **Новый тип стейджа: `mark-blocked` и расширение frontmatter** — Добавлены поля `auto_blocked_reason`, `auto_blocked_attempts`, `auto_blocked_at` для автоматического отслеживания причин и попыток блокировки тикетов. Стейдж `mark-blocked` позволяет устанавливать эти поля в зависимости от условий бизнес-логики.
+- **Новый тип стейджа: `manual-gate-human`** — Добавлен статус `human_ready` в `pick-next-task.js`. При достижении этого статуса задача ожидает ручного решения оператора перед продолжением выполнения.
+- **Хук одобрения в `move-ticket.js`** — Добавлен approval-hook, проверяющий наличие ожидающих решения одобрений перед перемещением тикета в терминальные состояния.
+- **Расширение START-лога полем `ticket="X"`** — Добавлено поле с идентификатором тикета в стартовый лог для улучшенной трассировки и связывания логов с конкретными задачами.
+- **Исправление `approval-pending.mjs` (поле `created_at`)** — Исправлено некорректное заполнение поля `created_at` при создании файлов ожидающих решения.
+
+> **Примечание:** версия 1.2.0 не была опубликована в npm. При выполнении `npm publish`
+> сработал prepublishOnly/postversion скрипт, автоматически поднявший версию до 1.2.1.
+> Git-тег `v1.2.0` (коммит 179d52b) соответствует состоянию до publish; `v1.2.1` (коммит 83d1b70) —
+> фактически опубликованной версии.
+
+### 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
+- Исправлено сохранение временной метки `created_at` в файлах одобрений (approval-pending.mjs)
+
+### 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

@@ -2,6 +2,33 @@
 - Добавлено упоминание `human-gate` в разделе про runner-стадии (пример конфига в pipeline.yaml: human-review-step типа manual-gate).
 - Добавлено упоминание `mark-blocked` как механизм нотификации autoblocked-тикетов (поля auto_blocked_reason/attempts/at).
 
+## Синглтон семантика Pipeline
+
+Система workflow реализует паттерн синглтона для выполнения пайплайна: одновременно разрешена только одна активная инстанция пайплайна для каждого проекта.
+
+### Семантика Синглтона
+При попытке запустить второй пайплайн, когда первый уже работает, система вернёт ошибку `PIPELINE_ALREADY_RUNNING`.
+
+### Структура `.workflow/logs/.pipeline.lock`
+Файл блокировки содержит следующие поля:
+- `pid`: ID процесса работающего пайплайна
+- `started_at`: Временная метка запуска пайплайна
+- `started_by`: Инициатор запуска пайплайна (cli | mcp | extension)
+- `run_id`: Уникальный идентификатор этого запуска
+- `pipeline_log`: Путь к файлу логов пайплайна
+- `project_root`: Корневая директория проекта
+- `pipeline_version`: Версия выполняемого пайплайна
+
+### Команды
+- `workflow run --project <path> [--started-by cli|mcp|extension] [--force]` - Запустить пайплайн для указанного проекта
+- `workflow stop --project <path> [--grace-sec N]` - Мягко остановить пайплайн (SIGTERM → SIGKILL после N секунд)
+- `--force` флаг - Обход блокировки (только для отладки, когда процесс зависает)
+
+### Восстановление
+Если файл блокировки устарел (процесс упал, но блокировка не удалена):
+1. Проверь, что процесс мёртв: `workflow stop --project <path>` (автоматически детектит устаревшие блокировки)
+2. Если стандартная остановка не решает проблему: `workflow run --force --project <path>`
+
 ## Runner-стадии
 
 В системе поддерживаются различные типы стадий для управления процессами разработки:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow-ai",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "AI Agent Workflow Coordinator — kanban-based pipeline for AI coding agents",
   "type": "module",
   "bin": {

package/src/lib/marker.mjs

@@ -0,0 +1,108 @@
+import fs from 'fs';
+import path from 'path';
+
+const MARKER_FILE = '.pipeline.lock';
+const LOGS_DIR = '.workflow/logs';
+
+/**
+ * Ensures the logs directory exists
+ */
+function ensureLogsDir(projectRoot) {
+  const logsPath = path.join(projectRoot, LOGS_DIR);
+  if (!fs.existsSync(logsPath)) {
+    fs.mkdirSync(logsPath, { recursive: true });
+  }
+}
+
+/**
+ * Atomic write via temp file + rename.
+ * Fallback to O_EXCL (wx flag) on EXDEV/ENOTSUP.
+ * Throws Error if marker file already exists (to prevent race conditions).
+ */
+export function writeMarker(projectRoot, payload) {
+  ensureLogsDir(projectRoot);
+  const markerPath = path.join(projectRoot, LOGS_DIR, MARKER_FILE);
+  const content = JSON.stringify(payload, null, 2);
+
+  // First, try exclusive create (O_EXCL) - this guarantees atomicity
+  // and prevents race conditions where two processes both think they created the marker
+  try {
+    const fd = fs.openSync(markerPath, 'wx');
+    fs.writeFileSync(fd, content, 'utf-8');
+    fs.closeSync(fd);
+    return;
+  } catch (openErr) {
+    if (openErr.code === 'EEXIST') {
+      // Marker already exists - another process created it
+      throw new Error(`Marker file already exists at ${markerPath}`);
+    }
+    // If EXDEV/ENOTSUP (cross-device link), fall back to temp+rename
+    if (openErr.code !== 'EXDEV' && openErr.code !== 'ENOTSUP') {
+      throw openErr;
+    }
+  }
+
+  // Fallback: temp file + rename (less atomic but works across devices)
+  const tempPath = markerPath + '.tmp.' + process.pid + '.' + Date.now();
+  try {
+    fs.writeFileSync(tempPath, content, 'utf-8');
+    fs.renameSync(tempPath, markerPath);
+    return;
+  } catch (renameErr) {
+    // Cleanup temp file if it still exists
+    try {
+      fs.unlinkSync(tempPath);
+    } catch {
+      // ignore
+    }
+
+    // If rename failed because marker was created by another process in the meantime
+    if (renameErr.code === 'EEXIST' || !fs.existsSync(tempPath)) {
+      throw new Error(`Marker file already exists at ${markerPath}`);
+    }
+
+    throw renameErr;
+  }
+}
+
+/**
+ * Reads and parses marker file. Returns null if file doesn't exist or is invalid.
+ */
+export function readMarker(projectRoot) {
+  const markerPath = path.join(projectRoot, LOGS_DIR, MARKER_FILE);
+  try {
+    const data = fs.readFileSync(markerPath, 'utf-8');
+    return JSON.parse(data);
+  } catch (err) {
+    // ENOENT (file missing) or SyntaxError (invalid JSON) → return null
+    return null;
+  }
+}
+
+/**
+ * Silently removes marker file. Ignores ENOENT.
+ */
+export function removeMarker(projectRoot) {
+  const markerPath = path.join(projectRoot, LOGS_DIR, MARKER_FILE);
+  try {
+    fs.unlinkSync(markerPath);
+  } catch (err) {
+    // Ignore ENOENT — file already gone
+    if (err.code !== 'ENOENT') {
+      // Log warning but don't throw — silent unlink
+      console.warn(`[marker] failed to remove ${markerPath}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Validates that marker exists and its pid matches expectedPid.
+ * Returns true only if both conditions hold, false otherwise.
+ */
+export function validateMarker(projectRoot, expectedPid) {
+  const marker = readMarker(projectRoot);
+  if (!marker) {
+    return false;
+  }
+  return marker.pid === expectedPid;
+}

package/src/lib/process-alive.mjs

@@ -0,0 +1,11 @@
+export function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0); // signal 0: existence check, не убивает процесс
+    return true;
+  } catch (err) {
+    // ESRCH = no process; EPERM = process exists but no permission
+    if (err.code === 'EPERM') return true;
+    return false;
+  }
+}

package/src/lib/stop-command.mjs

@@ -0,0 +1,82 @@
+import { readMarker, removeMarker } from './marker.mjs';
+import { processAlive } from './process-alive.mjs';
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+/**
+ * Sleep helper
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Gracefully stops a running pipeline.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {object} options - Options
+ * @param {number} [options.graceSec=10] - Grace period in seconds before SIGKILL
+ * @returns {object} Result object
+ *   - { ok: true, pid: number, escalated: boolean, duration_ms: number } on success
+ *   - { ok: true, was_stale: true } if marker existed but process was dead
+ *   - { ok: false, code: 'NOT_RUNNING' } if no marker found
+ */
+export async function stopPipeline(projectRoot, options = {}) {
+  const graceSec = options.graceSec ?? 10;
+  const marker = readMarker(projectRoot);
+
+  if (!marker) {
+    return { ok: false, code: 'NOT_RUNNING' };
+  }
+
+  if (!processAlive(marker.pid)) {
+    removeMarker(projectRoot);
+    return { ok: true, was_stale: true };
+  }
+
+  const startMs = Date.now();
+  const isWindows = process.platform === 'win32';
+
+  if (isWindows) {
+    // taskkill /T /F /PID <pid> — kills process tree immediately (forceful)
+    // No graceful period on Windows — taskkill /T does tree kill in one shot
+    try {
+      execSync(`taskkill /T /F /PID ${marker.pid}`, { stdio: 'ignore' });
+    } catch (err) {
+      // Ignore errors — process may have exited already
+    }
+  } else {
+    // POSIX: send SIGTERM, wait, then escalate to SIGKILL if needed
+    try {
+      process.kill(marker.pid, 'SIGTERM');
+    } catch (err) {
+      // Process may have exited between check and kill
+    }
+
+    let escalated = false;
+    const deadline = Date.now() + graceSec * 1000;
+
+    while (processAlive(marker.pid)) {
+      if (Date.now() >= deadline) {
+        try {
+          process.kill(marker.pid, 'SIGKILL');
+          escalated = true;
+        } catch (err) {
+          // Process may have already exited
+        }
+        break;
+      }
+      await sleep(200);
+    }
+  }
+
+  // Ensure marker is removed
+  removeMarker(projectRoot);
+
+  return {
+    ok: true,
+    pid: marker.pid,
+    escalated: isWindows ? false : (escalated || false),
+    duration_ms: Date.now() - startMs
+  };
+}

package/src/runner.mjs

@@ -9,6 +9,7 @@ import { findProjectRoot } from './lib/find-root.mjs';
 import { loadRules, scanStderrForFatalRule, classify } from './lib/error-classifier.mjs';
 import { snapshot, diff, isEmpty } from './lib/artifact-snapshot.mjs';
 import { markUnhealthy, isHealthy } from './lib/agent-health-registry.mjs';
+import { writeMarker, removeMarker } from './lib/marker.mjs';
 
 // ============================================================================
 // Logger — система логирования с уровнями DEBUG/INFO/WARN/ERROR
@@ -1564,7 +1565,7 @@ class PipelineRunner {
         }
         throw err;
       }
-    }
+    }
 
     /**
      * Читает approval-файл и парсит его как JSON.
@@ -1587,7 +1588,7 @@ class PipelineRunner {
         // Перебрасываем другие ошибки (например, fs-ошибки) без изменений
         throw err;
       }
-    }
+    }
 
     /**
      * Выполняет встроенный стейдж типа update-counter:
@@ -1756,7 +1757,7 @@ class PipelineRunner {
         this.logger.warn(`[${stageId}] manual-gate: aborted (runner stopped)`, stageId);
       }
       return { status: 'aborted', result: { step_id: stepId } };
-    }
+    }
 
   /**
    * Запускает основной цикл выполнения
@@ -1802,7 +1803,7 @@ class PipelineRunner {
            this.currentExecutor = new StageExecutor(this.config, this.context, this.counters, {}, this.fileGuard, this.logger, this.projectRoot);
            result = await this.currentExecutor.execute(this.currentStage);
            this.currentExecutor = null;
-         }
+         }
 
         this.logger.info(`Stage ${this.currentStage} completed with status: ${result.status}`, 'PipelineRunner');
 
@@ -2146,18 +2147,40 @@ async function runPipeline(argv = process.argv.slice(2)) {
     return { exitCode: 0, help: true };
   }
 
-  // Resolve config path
+  // Resolve config path and projectRoot
   if (!args.config) {
     const projectRoot = args.project ? path.resolve(args.project) : findProjectRoot();
     args.config = path.resolve(projectRoot, '.workflow/config/pipeline.yaml');
+    args.projectRoot = projectRoot;
   }
 
+  const projectRoot = args.projectRoot || (args.project ? path.resolve(args.project) : findProjectRoot());
+
   console.log('=== Workflow Runner ===');
   console.log(`Config: ${args.config}`);
   if (args.plan) console.log(`Plan: ${args.plan}`);
   if (args.project) console.log(`Project: ${args.project}`);
   console.log('');
 
+  // Write marker to protect against stale processes
+  try {
+    writeMarker(projectRoot, {
+      pid: process.pid,
+      timestamp: new Date().toISOString()
+    });
+  } catch (err) {
+    console.error(`[runner] failed to write marker: ${err.message}`);
+    return { exitCode: 1, error: 'Failed to acquire pipeline lock', details: err.message };
+  }
+
+  // Register signal handlers for cleanup
+  const cleanup = () => {
+    removeMarker(projectRoot);
+    process.exit(130); // 128 + SIGINT(2) — standard exit code for signal-terminated
+  };
+  process.once('SIGINT', cleanup);
+  process.once('SIGTERM', cleanup);
+
   try {
     const config = loadConfig(args.config);
     const errors = validateConfig(config);
@@ -2192,6 +2215,16 @@ async function runPipeline(argv = process.argv.slice(2)) {
     await new Promise(resolve => setTimeout(resolve, 100));
 
     return { exitCode: 1, error: err.message, stack: err.stack };
+  } finally {
+    // Ensure marker is cleaned up on normal exit
+    try {
+      removeMarker(projectRoot);
+    } catch (err) {
+      // ENOENT is expected, log warnings for other errors
+      if (err.code && err.code !== 'ENOENT') {
+        console.warn(`[runner] cleanup warning: ${err.message}`);
+      }
+    }
   }
 }
 

package/src/scripts/get-next-id.js

@@ -85,7 +85,7 @@ function readPrefixesFromConfig() {
     throw new Error(`config.yaml not found: ${configPath}`);
   }
 
-  const text = fs.readFileSync(configPath, "utf8");
+  const text = fs.readFileSync(configPath, "utf8");
   const lines = text.split(/\r?\n/);
 
   const prefixes = [];

package/src/skills/coach/SKILL.md

@@ -128,6 +128,7 @@ ticket_prefix: COACH
 **⚠️ Антипаттерн «уход в формулировки вместо root cause»:** стейкхолдер задаёт вопрос о наблюдаемом дефекте («почему не поймали?»), а коуч анализирует текст формулировок, семантику переносов, чеклисты — вместо того чтобы ответить на прямой вопрос: какой конкретный шаг в какой конкретной стадии не выполнил конкретное физическое действие (открыть файл, посмотреть на картинку, запустить команду). Формулировки — это причина второго порядка; причина первого порядка — «агент X не сделал действие Y». Всегда начинай с причины первого порядка, потом объясняй, почему инструкции это допустили.
 **⚠️ Антипаттерн «оценка по результату вместо сверки с инструкцией»:** при анализе действия агента — **не оценивай** его «разумность» или «допустимость» по своему суждению. Вместо этого открой скил агента и **дословно сверь** действие с инструкцией. Если инструкция говорит «разбей тикет», а агент объединил шаги — это нарушение, даже если результат выглядит «приемлемо». Коуч не имеет права смягчать finding на основании того, что дефект «небольшой» или «единичный» — скил либо нарушен, либо нет.
 **⚠️ Антипаттерн «пересказ вместо цитаты» при утверждениях о коде:** перед утверждением вида «скрипт/функция X использует/читает/пишет Y» обязан открыть файл и **дословно процитировать** строку, на которой это поведение происходит. Пересказ по памяти (даже свежей) теряет операторы-fallback (`a || b`, `a ?? b`), условные ветви, ранние return'ы — те детали, которые как раз и задают реальное поведение. Источник ошибки: агент видит ключевое слово в строке, строит «достаточное» утверждение о поведении и идёт дальше. Правило: если утверждение про код войдёт в финдинг, CHG, черновик правки или ответ стейкхолдеру — строка должна быть в отчёте целиком (либо скопированной в цитату, либо явной ссылкой `file:line`, открытой и перечитанной непосредственно перед утверждением).
+**⚠️ Антипаттерн «отрицательное утверждение о capability инструмента без проверки» (расширение предыдущего):** правило «дословная цитата» применяется не только к **позитивным** утверждениям («X делает Y»), но и к **отрицательным** («инструмент/фреймворк/тест X **не умеет / не покрывает / не подходит для** Y»). Отрицательное утверждение о capability — такое же утверждение о коде, как и позитивное, и требует тех же доказательств: либо (1) Grep по тестам/коду проекта, использующим инструмент, на ключевой паттерн использования (например, для гипотезы «Playwright не покрывает extension popup» — `Grep "loadExtension|launchPersistentContext|chrome-extension://"` по `tests/`), либо (2) дословная цитата из официальной документации. Источник ошибки: агент экстраполирует «общеизвестное» назначение инструмента (Playwright = веб-сайты, jest = unit-тесты и т.п.) без проверки фактической практики проекта или актуальных возможностей. Триггер срабатывания: если в черновике финдинга/ответа есть конструкция «{инструмент} не {глагол} {объект}» и от неё зависит root cause или CHG — **обязательна** проверка перед показом стейкхолдеру. Без проверки финдинг невалиден, даже если интуиция кажется правильной.
 3. **Итеративность** — улучшай скилы инкрементально. Маленькие точечные улучшения > масштабные переписывания.
 4. **Обратная совместимость** — улучшения не должны ломать существующие воркфлоу и интеграции.
 5. **Актуальность знаний** — активно ищи в интернете лучшие практики, фреймворки и подходы для обогащения скилов.

package/src/skills/execute-task/SKILL.md

@@ -70,6 +70,14 @@ description: >
 |----------|----------------|
 | `algorithms/execution-strategy.md` | **ВСЕГДА** — стратегия анализа, выполнения и верификации задачи |
 
+## Загрузка шаблонов
+
+Подгружай из `templates/` при необходимости:
+
+| Шаблон | Когда загружать |
+|--------|----------------|
+| `templates/result-template.md` | При создании секции `## Result` в тикете — структура и правила заполнения |
+
 ## Шаги выполнения
 
 ### 1. Прочитать тикет
@@ -122,6 +130,8 @@ description: >
 3. Прочитать `context.notes` — дополнительный контекст от создателя тикета
 4. Если тикет ссылается на план (`parent_plan`) — прочитать план для понимания общей картины
 
+**⛔ Валидация путей перед Edit:** если DoD требует изменить конкретный файл, указанный в `context.files` или описании, используй **ровно тот путь**, который указан. Перед каждым Edit сверь целевой путь с путём из контекста тикета. Одноимённый файл в другой директории — не целевой файл. Пример нарушения: тикет указывает `workflow-ai/README.md`, агент редактирует `./README.md`.
+
 ### 5. Выполнить работу и фиксировать результат инкрементально
 
 Действовать по описанию и DoD тикета. Подход определяется **содержимым тикета**, а не типом:
@@ -131,6 +141,8 @@ description: >
 - Если тикет требует тестирования — выполнить чеклист проверок из DoD, зафиксировать pass/fail по каждому пункту
 - Если тикет требует исследования — использовать доступные инструменты для сбора данных, подкреплять источниками
 
+**⛔ Перед вставкой кода в существующий файл — прочитай целевой участок и пойми его структуру.** Определи границы функции/класса/блока, в который вставляешь код. Вставляй код в семантически правильное место, а не в произвольную точку файла. Если не уверен в месте вставки — прочитай окружающий контекст (строки до и после) и убедись, что вставка не разрывает существующую структуру.
+
 **⚠️ ИНКРЕМЕНТАЛЬНАЯ ЗАПИСЬ (ОБЯЗАТЕЛЬНО):**
 
 После выполнения **каждого пункта** — **сразу** запиши результат в тикет:
@@ -156,7 +168,7 @@ description: >
 
 К этому моменту секция Result уже содержит результаты по каждому пункту (записаны инкрементально на шаге 5). Осталось:
 
-- Обновить/добавить **Summary** — краткое резюме всей работы
+- Обновить/добавить **Что сделано** — краткое резюме всей работы
 - Дополнить **Изменённые файлы** и **Заметки** если нужно
 - **НЕ удалять и не переписывать** уже записанные результаты
 
@@ -191,6 +203,14 @@ description: >
 
 ### 9. Вывести структурированный результат
 
+**⛔ Перед выводом RESULT пройди все три GATE из `workflows/execute.md` (шаг 6).** GATE-1 (Edit-проверка), GATE-2 (механическая Read-проверка), GATE-3 (self-check). При любом нарушении — вернись к шагам 5–7.
+
+⛔ **GATE-1 — EDIT-ПРОВЕРКА (выполни ПЕРЕД Read-проверкой):**
+
+За текущую сессию ты должен был вызвать инструмент **`Edit`** на файл тикета как минимум дважды: один раз для обновления DoD-чекбоксов (`[ ]` → `[x]`), один раз для записи секции Result. Если ни одного вызова `Edit` на файл тикета `.workflow/tickets/in-progress/{TICKET-ID}.md` не было — секция Result физически пустая и DoD не отмечен, независимо от написанного в stdout. Это призрачное выполнение (ограничение #9). Немедленно вернись к шагам 5–7.
+
+**Ключевой принцип:** stdout (текст ответа) ≠ файл тикета. Результат существует только в том, что записано через инструмент `Edit`.
+
 **⛔ ОБЯЗАТЕЛЬНАЯ МЕХАНИЧЕСКАЯ ПРОВЕРКА — перечитай файл тикета перед RESULT:**
 
 Перед выводом `---RESULT---` выполни `Read` на файл тикета (`.workflow/tickets/in-progress/{TICKET-ID}.md`) и глазами убедись:
@@ -219,6 +239,7 @@ description: >
 - Нет побочных эффектов — не созданы тикеты/планы, не перемещены файлы
 - Поля `status` и `completed_at` не записаны в файл тикета ни в каком виде
 - Секция `## Ревью` не создавалась и не редактировалась тобой
+- Все временные/промежуточные файлы и пустые директории, созданные в ходе работы и не являющиеся deliverable, удалены; файлы, путь которых зависит от конфига инструмента (mock/test/fixture/snapshot/output), лежат в директории, указанной в конфиге, а не в произвольном месте
 
 **⛔ ФОРМАТ STDOUT — СТРОГО:**
 
@@ -273,6 +294,12 @@ status: default
 
    При визуальных/семантических/поведенческих критериях в Result **явно обоснуй**, почему структурной проверки недостаточно (одна строка). Полная таблица соответствий — `algorithms/execution-strategy.md` раздел «Соразмерность проверки критерию».
 
+9. **Configured paths и cleanup** — файлы, создаваемые во время работы тикета, размещай в местах, явно указанных в конфиге соответствующего инструмента. Перед созданием файла, путь которого может зависеть от конфигурации (mock, тест, фикстура, стаб, snapshot, сгенерированный artifact, временный файл сборки и подобное) — **прочитай соответствующий конфиг проекта**, найди в нём поле target-директории (`roots`, `testDir`, `paths`, `output`, `outDir`, `srcDir` или аналог в конфиге твоего инструмента) и помести файл туда. Создавать файл в корне репозитория без проверки конфига запрещено.
+
+   **После удаления временных/ошибочных файлов — проверь и удали пустые родительские директории**, созданные в ходе тикета. Каждая созданная директория — твоя ответственность вплоть до закрытия тикета. Пустая папка или артефакт вне scope, оставленные в репозитории, — побочный эффект (см. принцип 4 «No Side Effects»).
+
+   ⛔ **Антипаттерн:** создал файл в корне (mock/snapshot/test) → инструмент не подхватил из-за неправильного пути → удалил файл, но оставил пустую папку. Лечение: до создания — проверка конфига; после rm — удаление пустых директорий.
+
 ## Формат вывода
 
 - Русский язык