@nitra/cursor 3.28.0 → 4.0.0

package/skills/docgen/js/docgen-gen.mjs

@@ -1,62 +1,14 @@
 /** @see ./docs/docgen-gen.md */
 import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
-import { request } from 'node:http'
+import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
-import Anthropic from '@anthropic-ai/sdk'
+import { resolveModel } from '../../../lib/models.mjs'
 import { extractFacts } from './docgen-extract.mjs'
-import { sectionMessages, oneShotMessages, STYLE, oneShotPromptText } from './docgen-prompts.mjs'
+import { STYLE, oneShotPromptText, sectionMessages } from './docgen-prompts.mjs'
 
 const QUALITY_THRESHOLD = 70
 
-/** Один виклик чату до ollama зі streaming (токени стримуються → socket активний, жодного timeout). */
-async function ollamaChat(messages, { model, numPredict = 600 }) {
-  const body = JSON.stringify({
-    model,
-    messages,
-    stream: true,
-    think: false,
-    options: { num_ctx: 8192, temperature: 0.2, num_predict: numPredict },
-    keep_alive: '15m'
-  })
-  return new Promise((resolve, reject) => {
-    const req = request(
-      {
-        hostname: 'localhost',
-        port: 11434,
-        path: '/api/chat',
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }
-      },
-      res => {
-        let text = '',
-          genTok = 0,
-          buf = ''
-        res.on('data', chunk => {
-          buf += chunk.toString()
-          const lines = buf.split('\n')
-          buf = lines.pop()
-          for (const line of lines) {
-            if (!line.trim()) continue
-            try {
-              const j = JSON.parse(line)
-              text += j.message?.content ?? ''
-              if (j.done) genTok = j.eval_count ?? 0
-            } catch {
-              /* partial line */
-            }
-          }
-        })
-        res.on('end', () => resolve({ text, genTok }))
-        res.on('error', reject)
-      }
-    )
-    req.on('error', reject)
-    req.write(body)
-    req.end()
-  })
-}
-
 /** Прибирає ```-обгортку й випадковий провідний `##`-заголовок із секції. */
 function stripSection(text) {
   let t = text.trim()
@@ -137,73 +89,24 @@ function scoreDoc(md, facts) {
   return { score: Math.max(0, score), issues }
 }
 
-const SCORE_RUBRIC = `Оціни якість документації для JavaScript-модуля за 4 критеріями (1-3 кожен):
-
-- огляд: 3=описує роль модуля в системі (ЩО і НАВІЩО); 2=частково розмитий; 1=відсутній або перераховує функції
-- поведінка: 3=бізнес-терміни, без деталей реалізації; 2=деякі impl-деталі; 1=переважно реалізація або відсутня
-- гарантії: 3=лише реальні інваріанти підтверджені кодом, без галюцинацій; 2=частково правильні; 1=вигадані або відсутні
-- стиль: 3=без сигнатур/internal-імен, правильна markdown-структура; 2=дрібні порушення; 1=сигнатури/internal-імена/відсутні заголовки
-
-Відповідай ТІЛЬКИ JSON без пояснень:
-{"огляд":N,"поведінка":N,"гарантії":N,"стиль":N,"issues":["коротко про кожен мінус 1-5 слів"]}`
-
-/**
- * Stage 2.5 cloud: Claude Haiku оцінює якість доку проти коду + фактів.
- * Використовує найдешевшу хмарну модель — haiku — для мінімальної вартості судді.
- * @returns {{ score: number, scores: object, issues: string[], tok: number }}
- */
-async function cloudScoreDoc(md, facts, src, model = 'claude-haiku-4-5-20251001') {
-  const client = new Anthropic()
-  const factsTxt = [
-    facts.exports?.length ? `Публічні функції: ${facts.exports.map(e => e.name).join(', ')}` : '',
-    facts.internalSymbols?.length ? `Внутрішні (не публічні): ${facts.internalSymbols.join(', ')}` : '',
-    facts.markers?.caches ? 'Кешування: є' : 'Кешування: немає',
-    facts.markers?.network ? 'Мережа: є' : 'Мережа: немає',
-    facts.markers?.readOnly ? 'Read-only (не змінює файли/стан)' : ''
-  ]
-    .filter(Boolean)
-    .join('\n')
-
-  const msg = await client.messages.create({
-    model,
-    max_tokens: 256,
-    system: SCORE_RUBRIC,
-    messages: [
-      {
-        role: 'user',
-        content: [
-          { type: 'text', text: `ФАКТИ:\n${factsTxt}`, cache_control: { type: 'ephemeral' } },
-          { type: 'text', text: `КОД:\n\`\`\`\n${src.slice(0, 4000)}\n\`\`\``, cache_control: { type: 'ephemeral' } },
-          { type: 'text', text: `ДОКУМЕНТАЦІЯ:\n${md}` }
-        ]
-      }
-    ]
+/** Викликає pi і повертає stdout. Кидає якщо pi повертає ненульовий код. */
+function callPi(prompt, model, timeoutMs) {
+  const modelArgs = model ? ['--model', model] : []
+  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
+    encoding: 'utf8',
+    timeout: timeoutMs
   })
-  const tok = (msg.usage?.input_tokens ?? 0) + (msg.usage?.output_tokens ?? 0)
-  try {
-    const j = JSON.parse(msg.content[0]?.text ?? '{}')
-    const total = (((j.огляд ?? 0) + (j.поведінка ?? 0) + (j.гарантії ?? 0) + (j.стиль ?? 0)) / 12) * 100
-    return { score: Math.round(total), scores: j, issues: j.issues ?? [], tok }
-  } catch {
-    return { score: 50, scores: {}, issues: ['parse-error'], tok }
-  }
+  if (r.error) throw new Error(`pi error: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`pi exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
+  return r.stdout?.trim() ?? ''
 }
 
-/** Tier 2: хмарний fallback через Claude коли local-score < QUALITY_THRESHOLD. */
-async function claudeOneShot(facts, src, model = 'claude-sonnet-4-6') {
-  const client = new Anthropic()
-  const prompt = oneShotPromptText(facts, src)
-  const msg = await client.messages.create({
-    model,
-    max_tokens: 1500,
-    system: STYLE,
-    messages: [{ role: 'user', content: prompt }]
-  })
-  const text = msg.content[0]?.text ?? ''
-  const genTok = msg.usage?.output_tokens ?? 0
+/** One-shot: один pi-виклик на весь документ. */
+function piOneShot(facts, src, model, timeoutMs = 120_000) {
+  const text = callPi(`${STYLE}\n\n${oneShotPromptText(facts, src)}`, model, timeoutMs)
   let md = stripSignatures(stripSection(text))
   if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  return { md: md + '\n', genTok }
+  return { md: md + '\n', genTok: 0 }
 }
 
 /** Stage 3: фіксовані заголовки у фіксованому порядку. */
@@ -222,55 +125,44 @@ function assemble(stem, sections) {
   return parts.join('\n\n') + '\n'
 }
 
-/** Оркестрований режим: секційно-мінімальний контекст — код інгестується лише в `behavior`. */
-async function generateOrchestrated(facts, src, model) {
+/**
+ * Orchestrated: N окремих pi-викликів, по одному на секцію.
+ * Код потрапляє лише в `behavior`; решта секцій — на мінімальному факт-листі.
+ */
+function piOrchestrated(facts, src, model, timeoutMs) {
   const sections = {}
-  let genTok = 0
   for (const s of sectionMessages(facts, src)) {
-    const { text, genTok: g } = await ollamaChat(s.messages, { model, numPredict: s.numPredict })
-    sections[s.key] = stripSignatures(stripSection(text))
-    genTok += g
+    // messages = [{role:'system',content}, {role:'user',content}] → plain text prompt для pi
+    const prompt = s.messages.map(m => m.content).join('\n\n')
+    sections[s.key] = stripSignatures(stripSection(callPi(prompt, model, timeoutMs)))
   }
-  return { md: assemble(basename(facts.relPath), sections), genTok }
+  return { md: assemble(basename(facts.relPath), sections), genTok: 0 }
 }
 
-/** One-shot режим: один промпт на весь документ. */
-async function generateOneShot(facts, src, model) {
-  const { text, genTok } = await ollamaChat(oneShotMessages(facts, src), { model, numPredict: 1500 })
-  let md = stripSignatures(stripSection(text)) // Stage-2 лінт і для one-shot
-  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  return { md: md + '\n', genTok }
-}
 
-/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без локального проходу). */
+
+/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без Tier 1 проходу). */
 const DEFAULT_SYM_THRESHOLD = 4
-/** Максимальний час локальної генерації на один файл перед ескалацією у Tier 2. */
+/** Максимальний час Tier 1 генерації на один файл перед ескалацією у Tier 2. */
 const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
-
-/** Повертає promise, що відхиляється через `ms` мс з повідомленням про timeout. */
-function withTimeout(promise, ms) {
-  return Promise.race([
-    promise,
-    new Promise((_, reject) => setTimeout(() => reject(new Error(`local timeout after ${ms / 1000}s`)), ms))
-  ])
-}
+/** Дефолтна Tier 1 модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min'). */
+const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? resolveModel('min')
+/** Дефолтна Tier 2 модель: N_CURSOR_DOCGEN_CLOUD_MODEL → resolveModel('avg'). */
+const DEFAULT_CLOUD_MODEL = env.N_CURSOR_DOCGEN_CLOUD_MODEL ?? resolveModel('avg')
 
 /**
  * Головний API: файл → { md, genTok, ms, score, issues, tier }.
  *
  * Routing (sym-threshold):
- *   sym < symThreshold  → Tier 1 local (timeout: LOCAL_TIMEOUT_MS) + det-scorer
+ *   sym < symThreshold  → Tier 1 pi(resolveModel('min'), timeout=5хв) + det-scorer
  *                       → timeout або det-score < threshold → Tier 2
  *   sym >= symThreshold → Pre-routing одразу Tier 2
- *
- * @param {string}  cloudModel    — модель для Tier 2 генерації (Sonnet за замовч.)
  */
 export async function generateDoc(
   file,
   {
-    model = 'gemma3:4b',
-    mode = 'orchestrated',
-    cloudModel = 'claude-sonnet-4-6',
+    model = DEFAULT_LOCAL_MODEL,
+    cloudModel = DEFAULT_CLOUD_MODEL,
     threshold = QUALITY_THRESHOLD,
     symThreshold = DEFAULT_SYM_THRESHOLD
   } = {}
@@ -279,39 +171,24 @@ export async function generateDoc(
   const facts = extractFacts(src, file)
   const t0 = Date.now()
 
-  // Pre-routing: складні файли (sym ≥ symThreshold) → одразу Tier 2, не витрачаємо local-час
+  // Pre-routing: складні файли (sym ≥ symThreshold) → одразу Tier 2
   const complexity = facts.internalSymbols?.length ?? 0
-  if (complexity >= symThreshold && env.ANTHROPIC_API_KEY) {
-    const r2 = await claudeOneShot(facts, src, cloudModel)
-    return {
-      ...r2,
-      ms: Date.now() - t0,
-      score: null,
-      issues: [`pre-routed:sym=${complexity}`],
-      tier: 2,
-      model: cloudModel
-    }
+  if (complexity >= symThreshold && cloudModel) {
+    const r2 = piOneShot(facts, src, cloudModel)
+    return { ...r2, ms: Date.now() - t0, score: null, issues: [`pre-routed:sym=${complexity}`], tier: 2, model: cloudModel }
   }
 
-  // Tier 1: локальна генерація з timeout 5 хв — при перевищенні одразу Tier 2
+  // Tier 1: pi orchestrated (секція за секцією), timeout на секцію = LOCAL_TIMEOUT_MS
+  // facts.unsupported → one-shot (структура файлу нестандартна)
   let r
   try {
-    const localPromise =
-      facts.unsupported || mode === 'oneshot'
-        ? generateOneShot(facts, src, model)
-        : generateOrchestrated(facts, src, model)
-    r = await withTimeout(localPromise, LOCAL_TIMEOUT_MS)
+    r = facts.unsupported
+      ? piOneShot(facts, src, model, LOCAL_TIMEOUT_MS)
+      : piOrchestrated(facts, src, model, LOCAL_TIMEOUT_MS)
   } catch (e) {
-    if (env.ANTHROPIC_API_KEY) {
-      const r2 = await claudeOneShot(facts, src, cloudModel)
-      return {
-        ...r2,
-        ms: Date.now() - t0,
-        score: null,
-        issues: [`local-timeout: ${e.message}`],
-        tier: 2,
-        model: cloudModel
-      }
+    if (cloudModel) {
+      const r2 = piOneShot(facts, src, cloudModel)
+      return { ...r2, ms: Date.now() - t0, score: null, issues: [`tier1-error: ${e.message}`], tier: 2, model: cloudModel }
     }
     throw e
   }
@@ -319,27 +196,26 @@ export async function generateDoc(
   // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
   const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
 
-  if (detScore < threshold && env.ANTHROPIC_API_KEY) {
-    const r2 = await claudeOneShot(facts, src, cloudModel)
+  if (detScore < threshold && cloudModel) {
+    const r2 = piOneShot(facts, src, cloudModel)
     return { ...r2, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 2, model: cloudModel }
   }
 
   return { ...r, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 1, model }
 }
 
-// CLI: node docgen-gen.mjs <file> [--oneshot] [--model <m>] [--sym-threshold N] [--tier-only]
+// CLI: node docgen-gen.mjs <file> [--model <m>] [--sym-threshold N] [--tier-only]
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 if (isRunAsCli(import.meta.url)) {
   const args = process.argv.slice(2)
   const file = args.find(a => !a.startsWith('--'))
-  const mode = args.includes('--oneshot') ? 'oneshot' : 'orchestrated'
   const tierOnly = args.includes('--tier-only')
   const mi = args.indexOf('--model')
-  const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
+  const model = mi >= 0 ? args[mi + 1] : DEFAULT_LOCAL_MODEL
   const si = args.indexOf('--sym-threshold')
   const symThreshold = si >= 0 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
   if (!file) {
-    console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--model <m>] [--sym-threshold N] [--tier-only]')
+    console.error('Usage: node docgen-gen.mjs <file> [--model <m>] [--sym-threshold N] [--tier-only]')
     process.exit(1)
   }
   if (tierOnly) {
@@ -354,8 +230,8 @@ if (isRunAsCli(import.meta.url)) {
     process.stdout.write(`${icon} ${label}  |  ${file}\n`)
     process.exit(0)
   }
-  const r = await generateDoc(file, { model, mode, symThreshold })
+  const r = await generateDoc(file, { model, symThreshold })
   const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
-  process.stderr.write(`[tier${r.tier} ${mode}] ${r.ms}ms / ${r.genTok} tok / score=${r.score}${issuesTxt}\n`)
+  process.stderr.write(`[tier${r.tier} pi-orchestrated] ${r.ms}ms / score=${r.score}${issuesTxt}\n`)
   process.stdout.write(r.md)
 }

package/skills/fix/js/llm-worker.mjs

@@ -4,12 +4,12 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
-import { CLOUD_MIN, CLOUD_AVG } from '../../../lib/models.mjs'
+import { resolveModel } from '../../../lib/models.mjs'
 
-// Тир за замовчуванням: CLOUD_MIN → CLOUD_AVG при ескалації.
+// Тир за замовчуванням: min → avg при ескалації (каскад local→cloud).
 // Перевизначення через N_CURSOR_FIX_MODEL / N_CURSOR_FIX_MODEL_HEAVY.
-export const MODEL = env.N_CURSOR_FIX_MODEL ?? CLOUD_MIN
-export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? CLOUD_AVG
+export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
+export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
 /**
  * Витягує відносні шляхи файлів із violation output.

package/scripts/dispatcher/lib/active.mjs

@@ -1,222 +0,0 @@
-/**
- * Активний Раннер (spec §8.1 Фасад B): `run`/`resume`/`cancel`/`repair`. Зшиває
- * ensureWorktree + planner + executor + verify у повний 5-фазний цикл. Уся IO
- * ін'єктується (`runner`/`verify`/`commit`/`run`/`now`) — тестується без
- * реальних LLM/git/gates.
- */
-import { spawnSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { cwd as processCwd } from 'node:process'
-
-import { BudgetExceeded, withBudget } from './budget.mjs'
-import { ensureWorktree, realRun } from './commands.mjs'
-import { flowEventsPath } from './events.mjs'
-import { executePlan } from './executor.mjs'
-import { generatePlan } from './planner.mjs'
-import { runReview } from './reviewer.mjs'
-import { cleanupFlowSiblings, flowStatePath, readState, updateState, writeState } from './state-store.mjs'
-import { createRunner } from './subagent-runner.mjs'
-
-/**
- * Дефолтний commit: `git add -A && git commit -m` у worktree.
- * @param {string} cwd worktree
- * @param {string} msg повідомлення
- * @returns {void}
- */
-function defaultCommit(cwd, msg) {
-  spawnSync('git', ['add', '-A'], { cwd })
-  spawnSync('git', ['commit', '-m', msg], { cwd })
-}
-
-/**
- * Дефолтний verify для executor-а: проганяє gates і повертає verdict.
- * @param {string} cwd worktree
- * @returns {{ pass: boolean, failedOutput: string | null }} verdict
- */
-function defaultVerify(cwd) {
-  return runReview({ run: realRun, cwd, fingerprint: () => null })
-}
-
-/**
- * Читає `flow.autonomous` із `.n-cursor.json` (бюджет автономного режиму).
- * @param {string} cwd корінь
- * @returns {{ maxApiCalls?: number, maxCostUsd?: number, onBudgetExceeded?: string }} конфіг бюджету
- */
-function readFlowAutonomous(cwd) {
-  try {
-    const cfg = JSON.parse(readFileSync(join(cwd, '.n-cursor.json'), 'utf8'))
-    return cfg?.flow?.autonomous ?? {}
-  } catch {
-    return {}
-  }
-}
-
-/**
- * `flow run [--autonomous] <branch> "<task>"` — повний цикл: ensureWorktree →
- * план → executor. У `--autonomous` runner обгортається budget guard-ом (§9.4).
- * @param {string[]} rest аргументи (`--autonomous` + `<branch> <task...>`)
- * @param {{ runner?: object, verify?: (cwd: string) => object, commit?: (cwd: string, msg: string) => void, run?: (cmd: string, args: string[], opts: object) => object, autonomous?: boolean, budget?: object, cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
- * @returns {Promise<number>} exit code: 0 done, 1 fail, 2 blocked-on-human
- */
-export async function run(rest, deps = {}) {
-  const log = deps.log ?? console.error
-  const now = deps.now ?? Date.now
-  const autonomous = deps.autonomous ?? rest.includes('--autonomous')
-  const positional = rest.filter(a => !a.startsWith('--'))
-
-  const ew = ensureWorktree(positional, deps)
-  if (ew.code !== 0) return ew.code
-  const { worktreeDir, branch, desc, baseCommit } = ew
-  const statePath = flowStatePath(worktreeDir)
-  writeState(statePath, {
-    branch,
-    status: 'in_progress',
-    started_at: new Date(now()).toISOString(),
-    metadata: { base_commit: baseCommit },
-    plan: []
-  })
-
-  let runner
-  try {
-    runner = deps.runner ?? (await createRunner(deps))
-  } catch (error) {
-    log(`run: ${error.message}`)
-    return 1
-  }
-  if (autonomous) {
-    const budget = deps.budget ?? readFlowAutonomous(deps.cwd ?? processCwd())
-    runner = withBudget(runner, { maxApiCalls: budget.maxApiCalls, log })
-  }
-
-  try {
-    const plan = await generatePlan({ runner, task: desc, cwd: worktreeDir })
-    updateState(statePath, s => ({ ...s, plan }))
-    const result = await executePlan(
-      { statePath, eventsPath: flowEventsPath(worktreeDir) },
-      { runner, verify: deps.verify ?? defaultVerify, commit: deps.commit ?? defaultCommit, cwd: worktreeDir, log, now }
-    )
-    if (result.status === 'done') {
-      log('run: build done — далі `flow release`')
-      return 0
-    }
-    if (result.status === 'blocked-on-human') {
-      log(`run: blocked-on-human на кроці ${result.step}`)
-      return 2
-    }
-    return 1
-  } catch (error) {
-    if (error instanceof BudgetExceeded) {
-      log(`run: ${error.message} — abort`)
-      updateState(statePath, s => ({ ...s, status: 'failed' }))
-      return 1
-    }
-    log(`run: ${error.message}`)
-    return 1
-  }
-}
-
-/**
- * `flow resume` — продовжує з чекпойнта. Safe-resume (§4.1.7): скидає частковий
- * доробок до останнього коміту; застосовує HITL-відповіді як підказки й дає
- * крокам свіжі спроби.
- * @param {string[]} _rest аргументи (не використовуються)
- * @param {object} [deps] ін'єкції (як у `run`)
- * @returns {Promise<number>} exit code
- */
-export async function resume(_rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
-  const log = deps.log ?? console.error
-  const now = deps.now ?? Date.now
-  const run_ = deps.run ?? realRun
-
-  const statePath = flowStatePath(cwd)
-  const state = readState(statePath)
-  if (!state) {
-    log('resume: стану нема')
-    return 1
-  }
-
-  const openHitl = (state.hitl ?? []).filter(q => !q.answer)
-  if (state.status === 'blocked-on-human' && openHitl.length > 0) {
-    log(`resume: ще blocked — ${openHitl.length} відкритих HITL-питань (заповни answer і повтори)`)
-    return 2
-  }
-  if (!state.plan?.length) {
-    log('resume: нема плану')
-    return 1
-  }
-
-  // safe-resume: скинути частковий доробок невдалого кроку до останнього коміту
-  run_('git', ['reset', '--hard', 'HEAD'], { cwd })
-
-  // застосувати HITL-відповіді як hint + дати незавершеним крокам свіжі спроби
-  const answers = new Map((state.hitl ?? []).filter(q => q.answer).map(q => [q.step, q.answer]))
-  updateState(statePath, s => ({
-    ...s,
-    status: 'in_progress',
-    plan: s.plan.map(st =>
-      st.status === 'done'
-        ? st
-        : { ...st, retry_count: 0, ...(answers.has(st.step) ? { hint: answers.get(st.step) } : {}) }
-    ),
-    hitl: (s.hitl ?? []).map(q => (q.answer ? { ...q, status: 'answered' } : q))
-  }))
-
-  let runner
-  try {
-    runner = deps.runner ?? (await createRunner(deps))
-  } catch (error) {
-    log(`resume: ${error.message}`)
-    return 1
-  }
-
-  const result = await executePlan(
-    { statePath, eventsPath: flowEventsPath(cwd) },
-    { runner, verify: deps.verify ?? defaultVerify, commit: deps.commit ?? defaultCommit, cwd, log, now }
-  )
-  if (result.status === 'done') return 0
-  if (result.status === 'blocked-on-human') return 2
-  return 1
-}
-
-/**
- * `flow cancel` — скасування: прибирає transient sibling-и (стан/журнал/lock).
- * @param {string[]} _rest аргументи
- * @param {{ cwd?: string, log?: (m: string) => void }} [deps] ін'єкції
- * @returns {Promise<number>} 0
- */
-export async function cancel(_rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
-  const log = deps.log ?? console.error
-  cleanupFlowSiblings(cwd)
-  log('cancel: стан і sibling-и прибрано')
-  return 0
-}
-
-/**
- * `flow repair [--discard-step-work]` — fail-closed escape: діагностика стану або
- * жорстке скидання робочого дерева до HEAD (свідоме викидання доробку).
- * @param {string[]} rest аргументи
- * @param {{ run?: (cmd: string, args: string[], opts: object) => object, cwd?: string, log?: (m: string) => void }} [deps] ін'єкції
- * @returns {Promise<number>} exit code
- */
-export async function repair(rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
-  const log = deps.log ?? console.error
-  const run_ = deps.run ?? realRun
-
-  if (rest.includes('--discard-step-work')) {
-    run_('git', ['reset', '--hard', 'HEAD'], { cwd })
-    log('repair: робоче дерево скинуто до HEAD (--discard-step-work)')
-    return 0
-  }
-  try {
-    const state = readState(flowStatePath(cwd))
-    log(state ? `repair: стан валідний (status: ${state.status})` : 'repair: стану нема')
-    return 0
-  } catch (error) {
-    log(`repair: стан пошкоджено — ${error.message}. Спробуй \`flow repair --discard-step-work\` або \`flow cancel\`.`)
-    return 1
-  }
-}

package/scripts/dispatcher/lib/artifact.mjs

@@ -1,79 +0,0 @@
-/**
- * Спільні утиліти фаз `spec`/`plan` (Пасивний Турнікет): резолв traceable-
- * артефакту в `docs/<kind>/`, екстракт кроків плану зі секції `## Кроки`, і
- * read-only перевірка цілісності ланцюга через `n-cursor trace` (`trace.mjs`).
- *
- * Лінки front-matter (`spec.plan`/`plan.spec`/`plan.flow`) пише сам агент за
- * контрактом `flow.mdc` — тут лише ВЕРИФІКАЦІЯ (мутатора `trace link` нема).
- */
-import { existsSync, readdirSync, statSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { runTraceCli } from '../trace.mjs'
-
-/**
- * Резолвить артефакт у `docs/<kind>/`. Пріоритет: файли, чия назва містить
- * хвіст гілки (slug, напр. `flow-gate` з `claude/flow-gate`); серед них (або
- * серед усіх, якщо збігу нема) — **найсвіжіший за mtime**. Лексикографічний
- * вибір був хибним при кількох артефактах на одну дату (виявлено dogfood'ом).
- * @param {string} cwd корінь worktree
- * @param {'specs' | 'plans'} kind підкаталог `docs`
- * @param {string} [branch] гілка задачі — для пріоритету за slug
- * @returns {string | null} абсолютний шлях або null, якщо каталог/файли відсутні
- */
-export function resolveArtifact(cwd, kind, branch) {
-  const dir = join(cwd, 'docs', kind)
-  if (!existsSync(dir)) return null
-  const md = readdirSync(dir).filter(f => f.endsWith('.md'))
-  if (md.length === 0) return null
-
-  const slug = branch ? branch.split('/').pop() : null
-  const matched = slug ? md.filter(f => f.includes(slug)) : []
-  const pool = matched.length > 0 ? matched : md
-
-  const best = pool
-    .map(f => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
-    .toSorted((a, b) => a.mtime - b.mtime || (a.f < b.f ? -1 : 1))
-    .at(-1)
-  return join(dir, best.f)
-}
-
-/** Маркер критерію приймання в рядку кроку (порівняння — case-insensitive). */
-const ACCEPTANCE_MARK = '— acceptance:'
-/** Лише цифри — перевірка нумерації кроку (лінійний, без backtracking). */
-const DIGITS_RE = /^\d+$/u
-
-/**
- * Кроки зі секції плану — нумерований список `N. <task> — acceptance: <crit>`.
- * Best-effort парсинг через `indexOf` (без regex-backtracking): рядки поза
- * форматом ігноруються.
- * @param {string} text вміст plan-doc
- * @returns {{ task: string, acceptance?: string }[]} кроки у порядку появи
- */
-export function extractSteps(text) {
-  const steps = []
-  for (const raw of String(text).split('\n')) {
-    const line = raw.trim()
-    const dot = line.indexOf('. ')
-    if (dot <= 0 || !DIGITS_RE.test(line.slice(0, dot))) continue
-    const body = line.slice(dot + 2).trim()
-    const sep = body.toLowerCase().indexOf(ACCEPTANCE_MARK)
-    if (sep === -1) {
-      steps.push({ task: body })
-    } else {
-      steps.push({ task: body.slice(0, sep).trim(), acceptance: body.slice(sep + ACCEPTANCE_MARK.length).trim() })
-    }
-  }
-  return steps
-}
-
-/**
- * Read-only перевірка цілісності ланцюга артефактів (не мутує — лише сигнал).
- * @param {string} cwd корінь worktree
- * @param {(cwd: string) => number} [runTrace] runner trace (0 — цілісно, 1 — розрив); ін'єкція для тестів
- * @returns {boolean} true, якщо ланцюг цілісний
- */
-export function verifyTrace(cwd, runTrace) {
-  const run = runTrace ?? (c => runTraceCli([], { cwd: c, log: () => {} }))
-  return run(cwd) === 0
-}