@nitra/cursor 1.41.1 → 3.0.0

package/scripts/dispatcher/lib/commands.mjs

@@ -0,0 +1,193 @@
+/**
+ * Handler-и підкоманд `flow` (spec §8). Уся IO — через ін'єктовані `run`/`log`/
+ * `fingerprint`/`now`, щоб логіку тестувати без реальних процесів.
+ *
+ * Ф2 (Пасивний Турнікет): `init` (worktree + стан), `verify` (Суддя), `release`
+ * (change + completion snapshot). `run`/`resume`/`cancel`/`repair` — Ф4.
+ */
+import { spawnSync } from 'node:child_process'
+import { isAbsolute, join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { worktreePaths } from '../../lib/worktree.mjs'
+import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
+import { flowEventsPath } from './events.mjs'
+import { runReview } from './reviewer.mjs'
+import { buildCompletionSnapshot, writeSummaryToTaskRecord } from './snapshot.mjs'
+import { flowStatePath, readState, recordTransition, writeState } from './state-store.mjs'
+
+/**
+ * Реальний sync-runner із захопленням виводу.
+ * @param {string} cmd виконуваний
+ * @param {string[]} args аргументи
+ * @param {object} [opts] додаткові опції spawnSync (напр. `cwd`)
+ * @returns {{ status: number, stdout: string, stderr: string }} результат
+ */
+export function realRun(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts })
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/**
+ * Чи `cwd` — уже linked worktree (не основний checkout і не submodule).
+ * @param {(cmd: string, args: string[], opts: object) => { status: number, stdout: string }} run runner
+ * @param {string} cwd робочий каталог
+ * @returns {boolean} true, якщо вже в worktree
+ */
+function inLinkedWorktree(run, cwd) {
+  const gitDir = run('git', ['rev-parse', '--git-dir'], { cwd })
+  const gitCommon = run('git', ['rev-parse', '--git-common-dir'], { cwd })
+  if ((gitDir.status ?? 1) !== 0 || (gitCommon.status ?? 1) !== 0) return false
+  const superproject = run('git', ['rev-parse', '--show-superproject-working-tree'], { cwd })
+  const isSubmodule = (superproject.stdout ?? '').trim() !== ''
+  return !isSubmodule && (gitDir.stdout ?? '').trim() !== (gitCommon.stdout ?? '').trim()
+}
+
+/**
+ * `flow init <branch> "<опис>"` — ізоляція + ініціалізація стану (§8.1). Якщо вже
+ * в worktree — не вкладає новий (detect existing isolation).
+ * @param {string[]} rest аргументи: `<branch> <опис...>`
+ * @param {{ run?: (cmd: string, args: string[], opts: object) => { status: number, stdout: string, stderr: string }, cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+/**
+ * Гарантує worktree для задачі: парсить `<branch> <опис>`, детектить існуючу
+ * ізоляцію (§8.1) або створює новий worktree, читає `base_commit`. Спільне для
+ * `init` (Фасад A) і `run` (Фасад B).
+ * @param {string[]} rest аргументи `<branch> <опис...>`
+ * @param {{ run?: (cmd: string, args: string[], opts: object) => object, cwd?: string, log?: (m: string) => void }} [deps] ін'єкції
+ * @returns {{ code: number, worktreeDir?: string, branch?: string, desc?: string, baseCommit?: string | null }} результат
+ */
+export function ensureWorktree(rest, deps = {}) {
+  const run = deps.run ?? realRun
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+
+  const branch = rest[0]
+  const desc = rest.slice(1).join(' ').trim()
+  if (!branch || !desc) {
+    log('Usage: n-cursor flow <init|run> <branch> "<опис>"')
+    return { code: 1 }
+  }
+
+  let worktreeDir
+  if (inLinkedWorktree(run, cwd)) {
+    worktreeDir = cwd
+    log(`flow: уже в worktree (${cwd}) — не вкладаю новий`)
+  } else {
+    const add = run('npx', ['@nitra/cursor', 'worktree', 'add', branch, desc], { cwd })
+    if ((add.status ?? 1) !== 0) {
+      const detail = add.stderr ? `: ${add.stderr.trim()}` : ''
+      log(`flow: worktree add не вдався${detail}`)
+      return { code: 1 }
+    }
+    worktreeDir = worktreePaths(cwd, branch).checkout
+  }
+
+  const head = run('git', ['rev-parse', 'HEAD'], { cwd: worktreeDir })
+  const baseCommit = (head.status ?? 1) === 0 ? (head.stdout ?? '').trim() : null
+  return { code: 0, worktreeDir, branch, desc, baseCommit }
+}
+
+/**
+ * `flow init <branch> "<опис>"` — ізоляція + ініціалізація стану (§8.1).
+ * @param {string[]} rest аргументи `<branch> <опис...>`
+ * @param {{ run?: (cmd: string, args: string[], opts: object) => object, cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function init(rest, deps = {}) {
+  const ew = ensureWorktree(rest, deps)
+  if (ew.code !== 0) return ew.code
+  const now = deps.now ?? Date.now
+  const log = deps.log ?? console.error
+  const statePath = flowStatePath(ew.worktreeDir)
+  writeState(statePath, {
+    branch: ew.branch,
+    status: 'in_progress',
+    started_at: new Date(now()).toISOString(),
+    metadata: { base_commit: ew.baseCommit },
+    plan: []
+  })
+  log(`init: ${ew.branch} → ${statePath}`)
+  return 0
+}
+
+/**
+ * `flow verify` — проганяє Quality Gates у поточному worktree (Турнікет, §8.1).
+ * На фейл друкує вивід проваленого gate. Якщо поряд є стан — записує
+ * gate-результати + fingerprint. Read-only щодо коду.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {{ run?: (cmd: string, args: string[], opts: object) => { status: number, stdout: string, stderr: string }, cwd?: string, log?: (m: string) => void, fingerprint?: () => string | null }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0 — pass, 1 — fail)
+ */
+export async function verify(_rest, deps = {}) {
+  const run = deps.run ?? realRun
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const fingerprint = deps.fingerprint ?? (() => worktreeFingerprint())
+
+  const verdict = runReview({ run, cwd, fingerprint })
+
+  for (const g of verdict.gates) {
+    log(`${g.ok ? '✅' : '❌'} gate: ${g.name}`)
+  }
+  if (!verdict.pass && verdict.failedOutput) log(verdict.failedOutput)
+  log(verdict.pass ? '✅ verify: усі gate-и пройдено' : '❌ verify: провалено')
+
+  const statePath = flowStatePath(cwd)
+  if (readState(statePath)) {
+    recordTransition(
+      { statePath, eventsPath: flowEventsPath(cwd) },
+      { type: 'verify', pass: verdict.pass },
+      state => ({
+        ...state,
+        gates: verdict.gates,
+        fingerprint: verdict.fingerprint,
+        status: verdict.pass ? state.status : 'failed'
+      })
+    )
+  }
+
+  return verdict.pass ? 0 : 1
+}
+
+/**
+ * `flow release [--bump … --section … --message …]` — генерує `.changes` і пише
+ * completion snapshot (§3 Ф5, §7). Потребує наявного стану (`init`).
+ * @param {string[]} rest аргументи, що прокидаються у `n-cursor change`
+ * @param {{ run?: (cmd: string, args: string[], opts: object) => { status: number, stdout: string, stderr: string }, cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function release(rest, deps = {}) {
+  const run = deps.run ?? realRun
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const now = deps.now ?? Date.now
+
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('release: стану нема — спершу `flow init`')
+    return 1
+  }
+
+  const ch = run('npx', ['@nitra/cursor', 'change', ...rest], { cwd })
+  if ((ch.status ?? 1) !== 0) {
+    const detail = ch.stderr ? `: ${ch.stderr.trim()}` : ''
+    log(`release: change не вдався${detail}`)
+    return 1
+  }
+
+  const snapshot = buildCompletionSnapshot({ ...state, status: 'done' }, now)
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'release' },
+    state_ => ({ ...state_, status: 'done', completion: snapshot }),
+    now
+  )
+  if (state.task) {
+    writeSummaryToTaskRecord(isAbsolute(state.task) ? state.task : join(cwd, state.task), snapshot)
+  }
+  log('release: done')
+  return 0
+}

package/scripts/dispatcher/lib/events.mjs

@@ -0,0 +1,67 @@
+/**
+ * WAL — append-only журнал подій `flow` (spec §4.1.2, §9).
+ *
+ * Sibling-файл `.worktrees/<sanitized-branch>.events.jsonl` (JSON Lines). Єдиний
+ * журнал: субсумує і переходи стану (`step_*`, `blocked`…), і api-облік
+ * (`api_call`). Append-only → краш-безпечніший за перезапис: торваний останній
+ * рядок (краш посеред append) при читанні **толеруємо** (пропускаємо), а не
+ * валимо весь журнал.
+ *
+ * **WAL-інваріант** (забезпечує `state-store.recordTransition`): подію
+ * дописуємо ДО зміни високорівневого статусу у snapshot `.flow.json`.
+ *
+ * Усі шляхи — абсолютні (`no-relative-fs-path`).
+ */
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join } from 'node:path'
+
+/**
+ * Шлях sibling-журналу подій для checkout-каталогу worktree.
+ * @param {string} worktreeDir абсолютний шлях checkout (`…/.worktrees/feat-x`)
+ * @returns {string} `…/.worktrees/feat-x.events.jsonl`
+ */
+export function flowEventsPath(worktreeDir) {
+  if (!isAbsolute(worktreeDir)) {
+    throw new Error(`flowEventsPath: очікується абсолютний шлях (отримано: ${worktreeDir})`)
+  }
+  return join(dirname(worktreeDir), `${basename(worktreeDir)}.events.jsonl`)
+}
+
+/**
+ * Дописує одну подію (з міткою часу `at`) у журнал. Створює файл за потреби.
+ * @param {string} eventsPath абсолютний шлях `.events.jsonl`
+ * @param {object} event подія (напр. `{ type: 'step_started', step: 2 }`)
+ * @param {() => number} [now] фабрика часу (ms) — ін'єкція для тестів
+ * @returns {object} фактично записаний запис (зі `at`)
+ */
+export function appendEvent(eventsPath, event, now = Date.now) {
+  if (!isAbsolute(eventsPath)) {
+    throw new Error(`appendEvent: очікується абсолютний шлях (отримано: ${eventsPath})`)
+  }
+  const record = { at: new Date(now()).toISOString(), ...event }
+  appendFileSync(eventsPath, `${JSON.stringify(record)}\n`, 'utf8')
+  return record
+}
+
+/**
+ * Читає всі події. Відсутній файл → `[]`. Непарсабельні рядки (порожні або
+ * торваний останній) **пропускаються** (append-only толерантність).
+ * @param {string} eventsPath абсолютний шлях `.events.jsonl`
+ * @returns {object[]} розпарсені події у порядку запису
+ */
+export function readEvents(eventsPath) {
+  if (!isAbsolute(eventsPath)) {
+    throw new Error(`readEvents: очікується абсолютний шлях (отримано: ${eventsPath})`)
+  }
+  if (!existsSync(eventsPath)) return []
+  return readFileSync(eventsPath, 'utf8')
+    .split('\n')
+    .filter(line => line.trim() !== '')
+    .flatMap(line => {
+      try {
+        return [JSON.parse(line)]
+      } catch {
+        return []
+      }
+    })
+}

package/scripts/dispatcher/lib/executor.mjs

@@ -0,0 +1,102 @@
+/**
+ * Executor (spec §3 Ф3) — виконує план покроково через SubagentRunner + verify.
+ *
+ * Інваріанти:
+ *  - **мікропромпт зі стану** (§3 Ф3): субагент отримує лише поточний крок +
+ *    критерії + останню помилку, не історію переписки;
+ *  - **commit лише після зеленого verify** (§4.1.7): repair-спроби не комітять,
+ *    тож HEAD завжди = останній зелений крок;
+ *  - **repair ≤ maxRepairAttempts**, далі — HITL (`blocked-on-human`, §4.2).
+ *
+ * Усі побічні дії (`runner`/`verify`/`commit`) ін'єктуються — тестується без
+ * реальних LLM/git/gates.
+ */
+import { readState, recordTransition } from './state-store.mjs'
+
+/**
+ * Мікропромпт для кроку (§3 Ф3): лише поточний крок + критерії + остання помилка.
+ * @param {{ step: number, task: string, acceptance?: string, last_error?: string }} step крок плану
+ * @param {{ branch?: string }} state стан (для контексту гілки)
+ * @returns {string} промпт субагента
+ */
+export function microprompt(step, state) {
+  const lines = [
+    'Реалізуй РІВНО цей крок плану (не більше). Iron Law of TDD: спершу падаючі тести, тоді код.',
+    `Гілка: ${state.branch ?? '—'}`,
+    `Крок ${step.step}: ${step.task}`
+  ]
+  if (step.acceptance) lines.push(`Критерії приймання: ${step.acceptance}`)
+  if (step.hint) lines.push(`Підказка людини (HITL): ${step.hint}`)
+  if (step.last_error) lines.push(`Попередня спроба впала на перевірці:\n${step.last_error}\nВиправ це.`)
+  return lines.join('\n')
+}
+
+/**
+ * Оновлює крок плану за індексом (pure).
+ * @param {{ plan: object[] }} state стан
+ * @param {number} index індекс кроку
+ * @param {object} patch часткове оновлення кроку
+ * @returns {object} новий стан
+ */
+export function patchStep(state, index, patch) {
+  return { ...state, plan: state.plan.map((s, i) => (i === index ? { ...s, ...patch } : s)) }
+}
+
+/**
+ * Виконує план зі стану.
+ * @param {{ statePath: string, eventsPath: string }} paths шляхи стану й журналу
+ * @param {{ runner: { runStep: (prompt: string, opts?: object) => object }, verify: (cwd: string) => Promise<{ pass: boolean, failedOutput?: string }> | { pass: boolean, failedOutput?: string }, commit: (cwd: string, msg: string) => void, cwd?: string, maxRepairAttempts?: number, log?: (m: string) => void, now?: () => number }} deps ін'єкції
+ * @returns {Promise<{ status: 'done' | 'blocked-on-human', step?: number }>} результат
+ */
+export async function executePlan(paths, deps) {
+  const { runner, verify, commit, cwd, maxRepairAttempts = 3, log = () => {}, now = Date.now } = deps
+  let state = readState(paths.statePath)
+  if (!state?.plan?.length) {
+    throw new Error('executor: у стані немає плану — спершу planner')
+  }
+
+  for (let i = 0; i < state.plan.length; i++) {
+    if (state.plan[i].status === 'done') continue
+
+    let done = false
+    while (state.plan[i].retry_count < maxRepairAttempts && !done) {
+      const step = state.plan[i]
+      log(`executor: крок ${step.step} (спроба ${step.retry_count + 1})`)
+      await runner.runStep(microprompt(step, state), { cwd })
+      const verdict = await verify(cwd)
+      if (verdict.pass) {
+        commit(cwd, `flow: step ${step.step} — ${step.task}`) // commit ЛИШЕ після зеленого
+        state = recordTransition(paths, { type: 'step_done', step: step.step }, s => patchStep(s, i, { status: 'done' }), now)
+        done = true
+      } else {
+        state = recordTransition(
+          paths,
+          { type: 'step_retry', step: step.step },
+          s => patchStep(s, i, { retry_count: s.plan[i].retry_count + 1, last_error: verdict.failedOutput ?? null }),
+          now
+        )
+      }
+    }
+
+    if (!done) {
+      const failed = state.plan[i]
+      const question = {
+        id: `q-${i}`,
+        step: failed.step,
+        question: `Крок ${failed.step} «${failed.task}» не проходить verify після ${maxRepairAttempts} спроб. Що робити?`,
+        status: 'open',
+        answer: ''
+      }
+      recordTransition(
+        paths,
+        { type: 'blocked', step: failed.step },
+        s => ({ ...s, status: 'blocked-on-human', hitl: [...(s.hitl ?? []), question] }),
+        now
+      )
+      return { status: 'blocked-on-human', step: failed.step }
+    }
+  }
+
+  recordTransition(paths, { type: 'plan_done' }, s => ({ ...s, status: 'built' }), now)
+  return { status: 'done' }
+}

package/scripts/dispatcher/lib/flow-lock.mjs

@@ -0,0 +1,39 @@
+/**
+ * Серіалізація мутацій стану `flow` через **reuse** спільного `withLock`
+ * (spec §4.1.3). `withLock` уже коректно чистить stale-локи (TTL +
+ * `process.kill(pid,0)`) і релізить на SIGINT/SIGTERM — не дублюємо це.
+ *
+ * **Override для flow:** `onWaitTimeout: 'fail'` — на відміну від lint (де
+ * прийнятно «після таймауту запустити без локу»), мутацію стану двома writer-ами
+ * не допускаємо → fail-closed. Dedup за fingerprint вимкнено (`getFingerprint:
+ * () => null`): flow завжди має виконатись, а не пропуститись за «тим самим
+ * деревом».
+ *
+ * Лок-кеш — sibling `.worktrees/.flow-lock-<branch>/` (поряд зі станом), щоб не
+ * залежати від глобального кеш-каталогу.
+ */
+import { basename, dirname, isAbsolute, join } from 'node:path'
+
+import { withLock } from '../../utils/with-lock.mjs'
+
+/**
+ * Виконує `runFn` під per-branch локом flow. Кидає (fail-closed), якщо лок не
+ * вдалося взяти за `waitTimeout`.
+ * @param {string} worktreeDir абсолютний шлях checkout (`…/.worktrees/feat-x`)
+ * @param {() => unknown | Promise<unknown>} runFn критична секція
+ * @param {object} [opts] прокидається у `withLock` (напр. `waitTimeout`, `pollInterval`)
+ * @returns {Promise<unknown>} результат `runFn`
+ */
+export function withFlowLock(worktreeDir, runFn, opts = {}) {
+  if (!isAbsolute(worktreeDir)) {
+    throw new Error(`withFlowLock: очікується абсолютний шлях (отримано: ${worktreeDir})`)
+  }
+  const base = basename(worktreeDir)
+  const cacheDir = join(dirname(worktreeDir), `.flow-lock-${base}`)
+  return withLock(`flow-${base}`, runFn, {
+    onWaitTimeout: 'fail',
+    cacheDir,
+    getFingerprint: () => null,
+    ...opts
+  })
+}

package/scripts/dispatcher/lib/planner.mjs

@@ -0,0 +1,66 @@
+/**
+ * Декларативний планувальник (spec §3 Ф1). Просить субагента видати суворий
+ * покроковий JSON-план, парсить і **валідує** його (fail-closed на невалідному).
+ * Нормалізує кроки до `{ step, task, status: 'pending', retry_count: 0 }`.
+ */
+
+/**
+ * Системно-користувацький промпт планувальника.
+ * @param {string} task опис фічі
+ * @returns {string} промпт
+ */
+export function plannerPrompt(task) {
+  return [
+    'Ти — архітектор. Розбий задачу на суворий покроковий план реалізації.',
+    'Кожен крок — ≤ 5 хв розробки, з чіткими критеріями приймання коду.',
+    'Поверни ЛИШЕ JSON-масив без коментарів: [{ "task": "...", "acceptance": "..." }, ...].',
+    '',
+    `Задача: ${task}`
+  ].join('\n')
+}
+
+/**
+ * Парсить і валідує план із тексту відповіді (толерує markdown-огорожу).
+ * @param {string} text відповідь субагента
+ * @returns {{ step: number, task: string, status: string, retry_count: number, acceptance?: string }[]} нормалізований план
+ */
+export function parsePlan(text) {
+  const str = String(text)
+  const start = str.indexOf('[')
+  const end = str.lastIndexOf(']')
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error('planner: не знайдено JSON-масив плану — fail-closed')
+  }
+  let arr
+  try {
+    arr = JSON.parse(str.slice(start, end + 1))
+  } catch {
+    throw new Error('planner: невалідний JSON плану — fail-closed')
+  }
+  if (!Array.isArray(arr) || arr.length === 0) {
+    throw new Error('planner: план має бути непорожнім масивом — fail-closed')
+  }
+  return arr.map((s, i) => {
+    const task = typeof s === 'string' ? s : s?.task
+    if (!task || typeof task !== 'string') {
+      throw new Error(`planner: крок ${i} без текстового поля task — fail-closed`)
+    }
+    const step = { step: i, task, status: 'pending', retry_count: 0 }
+    if (s?.acceptance) step.acceptance = String(s.acceptance)
+    return step
+  })
+}
+
+/**
+ * Генерує план через субагента-планувальника.
+ * @param {{ runner: { runStep: (prompt: string, opts?: object) => { ok: boolean, output: string } | Promise<{ ok: boolean, output: string }> }, task: string, cwd?: string }} input ін'єкції
+ * @returns {Promise<object[]>} нормалізований план
+ */
+export async function generatePlan({ runner, task, cwd }) {
+  const res = await runner.runStep(plannerPrompt(task), { cwd })
+  if (!res.ok) {
+    const detail = res.output ? `:\n${res.output}` : ''
+    throw new Error(`planner: субагент-планувальник завершився помилкою${detail}`)
+  }
+  return parsePlan(res.output)
+}

package/scripts/dispatcher/lib/reviewer.mjs

@@ -0,0 +1,38 @@
+/**
+ * Level-1 «Суддя» (spec §8.4): проганяє Quality Gates (§5) через **ін'єктований**
+ * `run`-runner і повертає структурований verdict. Не знає про LLM/API-ключі —
+ * чистий FS/Git/процеси. Один і той самий `runReview` обслуговує і Пасивний
+ * Турнікет (`flow verify`), і Активний Раннер (per-step Ф4).
+ *
+ * Fail-fast: на першому проваленому gate зупиняємось. Fingerprint дерева
+ * (`worktree-fingerprint`) фіксуємо лише на повному pass — щоб зберегти у стан і
+ * пізніше ловити stale-результат (§5).
+ */
+import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
+
+/** Канонічні gate-и verify (lint + coverage; coverage включає тести+мутації). */
+export const DEFAULT_GATES = [
+  { name: 'lint', cmd: ['npx', '@nitra/cursor', 'lint'] },
+  { name: 'coverage', cmd: ['npx', '@nitra/cursor', 'coverage'] }
+]
+
+/**
+ * Проганяє gate-и й повертає verdict.
+ * @param {{ run: (cmd: string, args: string[], opts: object) => { status: number, stdout?: string, stderr?: string }, cwd: string, gates?: { name: string, cmd: string[] }[], fingerprint?: () => string | null }} input ін'єкції
+ * @returns {{ pass: boolean, gates: { name: string, ok: boolean }[], failedOutput: string | null, fingerprint: string | null }} verdict
+ */
+export function runReview({ run, cwd, gates = DEFAULT_GATES, fingerprint = () => worktreeFingerprint() }) {
+  const results = []
+  let failedOutput = null
+  for (const g of gates) {
+    const r = run(g.cmd[0], g.cmd.slice(1), { cwd })
+    const ok = (r?.status ?? 1) === 0
+    results.push({ name: g.name, ok })
+    if (!ok) {
+      failedOutput = `${r?.stdout ?? ''}\n${r?.stderr ?? ''}`.trim() || null
+      break
+    }
+  }
+  const pass = results.length === gates.length && results.every(x => x.ok)
+  return { pass, gates: results, failedOutput, fingerprint: pass ? fingerprint() : null }
+}

package/scripts/dispatcher/lib/snapshot.mjs

@@ -0,0 +1,58 @@
+/**
+ * Completion snapshot (spec §3 Ф5, §7): перед cleanup transient `.flow.json`
+ * durable-слід задачі має пережити. Будуємо стислий summary і вписуємо його в
+ * task record (`docs/tasks/<id>.md`) між HTML-маркерами (idempotent upsert).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+
+const SUMMARY_START = '<!-- flow:summary:start -->'
+const SUMMARY_END = '<!-- flow:summary:end -->'
+
+/**
+ * Будує completion snapshot зі стану.
+ * @param {object} state стан `.flow.json`
+ * @param {() => number} [now] фабрика часу (ms)
+ * @returns {object} snapshot (status, branch, base_commit, gates, change, notified, finished_at)
+ */
+export function buildCompletionSnapshot(state, now = Date.now) {
+  return {
+    status: state.status ?? 'done',
+    branch: state.branch ?? null,
+    base_commit: state.metadata?.base_commit ?? state.base_commit ?? null,
+    gates: Object.fromEntries((state.gates ?? []).map(g => [g.name, g.ok ? 'ok' : 'fail'])),
+    change: state.change ?? null,
+    notified: state.notified ?? null,
+    finished_at: new Date(now()).toISOString()
+  }
+}
+
+/**
+ * Вставляє/оновлює блок Summary в markdown-контенті (між маркерами).
+ * @param {string} content вихідний markdown
+ * @param {object} snapshot completion snapshot
+ * @returns {string} оновлений markdown
+ */
+export function upsertSummaryBlock(content, snapshot) {
+  const block = `${SUMMARY_START}\n## Summary\n\`\`\`json\n${JSON.stringify(snapshot, null, 2)}\n\`\`\`\n${SUMMARY_END}`
+  const i = content.indexOf(SUMMARY_START)
+  const j = content.indexOf(SUMMARY_END)
+  if (i !== -1 && j !== -1 && j > i) {
+    return content.slice(0, i) + block + content.slice(j + SUMMARY_END.length)
+  }
+  return `${content.trimEnd()}\n\n${block}\n`
+}
+
+/**
+ * Вписує snapshot у task record (створює файл, якщо його нема).
+ * @param {string} taskPath абсолютний шлях `docs/tasks/<id>.md`
+ * @param {object} snapshot completion snapshot
+ * @returns {void}
+ */
+export function writeSummaryToTaskRecord(taskPath, snapshot) {
+  if (!isAbsolute(taskPath)) {
+    throw new Error(`writeSummaryToTaskRecord: очікується абсолютний шлях (отримано: ${taskPath})`)
+  }
+  const content = existsSync(taskPath) ? readFileSync(taskPath, 'utf8') : ''
+  writeFileSync(taskPath, upsertSummaryBlock(content, snapshot), 'utf8')
+}